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ABOUT THIS GUIDE 

Purpose We’ve designed this Z 80 Implem entor 1 s Guide 

to provide the information you need to know 
in order to generate various TurboDOS config- 
urations for Z80-based microcomputers, and to 
write the driver modules for various periph- 
eral devices. This document describes the 
modular architecture and internal programming 
conventions of TurboDOS, and explains the 
procedures for system generation, serializa- 
tion, and distribution. It also provides 
detailed interface specifications for hard- 
ware-dependent driver modules, and includes 
assembler source listings of sample drivers. 


Assumptions In writing this guide, we've assumed that you 

are an OEM, dealer, or sophisticated TurboDOS 
user, knowiedgable in Z80-based microcomputer 
hardware and assembly-language programming. 
We've also assumed you have read both the 
Us er ' s Guide and the ZM. Zipgrajmeiig. 
and are therefore familiar with the commands, 
external features, and internal functions of 
Z80 TurboDOS. 


Organization This guide starts with a section that de- 

scribes the architecture of TurboDOS. It 
explains the function of each internal module 
of the operating system, and how these 
modules may be combined to create the various 
configurations of TurboDOS. 

The next section explains the system genera- 
tion procedure in detail, and describes each 
TurboDOS parameter which can be modified 
during system generation. 

The third section of this guide explains the 
TurboDOS distribution procedure, including 
licensing, serialization, and support. 
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The fourth section is devoted to an in-depth 
discussion of internal programming conven- 
tions, aimed at the programmer writing 
drivers or resident processes for TurboDOS. 

The fifth section presents formal interface 
specifications for implementing hardware- 
dependent driver modules. 

This guide concludes with a large appendix 
containing assembler source listings of 
actual driver modules. The sample drivers 
cover a wide range of peripheral devices, and 
provide an excellent starting point for 
programmers involved in driver development. 


Organization 

(Continued) 
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ARCHITECTURE This section introduces you to the internal 

architecture of the TurboDOS operating sys- 
tem. TurboDOS is highly modular, consisting 
of more than forty separate functional 
modules distributed in relocatable form. 
These modules are "building blocks" that you 
can combine in various ways to produce a 
family of compatible operating systems. This 
section describes the modules in detail, and 
describes how to combine them in various 
configurations. 

Possible TurboDOS configurations include: 

. single-user without spooling 
. single-user with spooling 
, network server 

. simple network user (no local disks) 

. complex network user (with local disks) 

Numerous subtle variations are possible in 
each of these categories. 


Module Hierarchy The diagram on page 1-3 illustrates how the 

functional modules of TurboDOS interact. As 
the diagram shows, the architecture of Turbo- 
DOS can be viewed as a three-level hierarchy. 


Process Level The highest level of the hierarchy is the 

process l evel . TurboDOS can support many 
concurrent processes at this level. There is 
one active process that supports the local 
user who is executing commands and programs 
in the local TPA. There are also processes 
to support users running on other computers 
and making requests of the local computer 
over the network. There are processes to 
handle background printing (de-spooling) on 
local printers. Finally, there is a process 
that periodically causes disk buffers to be 
written out to disk. 
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Kernel Level The intermediate level of the hierarchy is 

the kernel level . The kernel supports the 93 
C-functions and T-£unctions, and controls the 
sharing of computer resources such as proces- 
sor time, memory, peripheral devices, and 
disk files. Processes make requests of the 
kernel through the entrypoint module OSNTRY, 
which decodes each C-function and T-function 
by number and invokes the appropriate kernel 
module. 


Driver Level The lowest level of the hierarchy is the 

drive r level , and contains all the device- 
dependent drivers necessary to interface 
TurboDOS to the particular hardware being 
used. Drivers must be provided for all peri- 
pherals, including console, printers, disks, 
communications channels, and network inter- 
face. Drivers are also required for the 
real-time clock (or other periodic interrupt 
source), and for bank-switched memory (if 
applicable) . 

TurboDOS is designed to interface with almost 
any kind of peripheral hardware. It operates 
most efficiently with interrupt-driven, DMA- 
type interfaces, but can also work fine using 
polled and programmed-I/O devices. 


TurboDOS Loader The TurboDOS loader OSLOAD.COM is a program 

containing an abbreviated version of the 
kernel and drivers. Its purpose is to load 
the full TurboDOS operating system from a 
disk file (OSSERVER.SYS) into memory at each 
system cold-start. 
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Process Level 




Despool 

Lcl Usr 

Net SVC 

BU££ 


DSPOOL 

LCLUSR 

NETSVC 

FLUS 


i 

LCLMSG 

NETTBL 



i 

LCLTBL 

1 



i 

CMDINT 

1 



i 

AUTLOD 

1 


Loader 

i 

SGLUSR 

1 


OSLOAD 

i 

AUTLOG 

1 


LDRMSG 
1 

i 

SUBMIT 
1 . 

1 



Kernel Level 


Bank 


Decode 

OSNTRY 


I 



Nonf ile 

l£ 

Met Reg 

-.Clock Support 

NONFIL 

FILMGR 

NETMGR 

RTCMGR 

DSPCHR 

CPMSUP 

FILSUP 

NETREQ 

1 

DSPSGL 

1 

FILCOM 

MSGFMT 

1 

MEMMGR 

1 

FILLOK 

NETTBL 

I 

COMSUB 

1 

FFOMGR 

NETLOD 

1 


1 

DRVLOK 

1 

1 


1 

FASLOD 

1 

1 


J 

I 

NORLOD 

1 

1 

1 

1 


1 

Printer 

i I 

Console Record, 

1 

i 

1 

1 

mitial 

LSTMGR 

CONMGR BUFMGR 

i 

1 

SYSNIT 

LSTTBL 

CONTBL DSKMGR 

i 

! 

1 

SPOOLR 

DOMGR DSKTBL 

i 

1 

1 

SPLMSG 

INPLN | 

i 

1 

1 



Printer Console Disk Ne,t^orJs 

COM DRV LSTDRA CONDRA DSKDRA CKTDRA RTCDRV HDWNIT 

Bank LSTDRB or DSKDRB CKTDRB or 

SELBNK etc. CONREM etc. etc. RTCNUL 


1-3 


TurboDOS 1.3 Z80 
Implementors Guide 


Process Modules 


ARCHITECTURE 
Process Modules 


Module 1 

Function 

LCLUSR 

Responsible for supporting local 
user's TPA activities. 

LCLMSG 

Contains all 0/S error messages. 

LCLTBL 

Local user option table. 

1 CMDINT 

Command interpreter, processes 
commands from local user. 

AUTLOD 

Autoload routine which processes 
COLDS TRT. AUT and WARMS TR T . AU T if 
present. 

SGLUSR 

Routine to flush/free disk buf- 
fers at each console input. Use 
for single-user configurations 
instead of FLUSHR. 

AUTLOG 

Automatic log-on routine. Used 
when full log-on security is not 
desired. See AUTUSR patch point. 

SUBMIT 

Routine to emulate CP/M proces- 
sing of $$$ . SUB files. Use is 
not recommended due to signifi- 
cant performance penalty. 

NETSVC 

Services network requests from 
other processors on the network. 

NETTBL 

Tables to define local network 
topology, used by NETSVC+NETREQ . 

DSPOOL 

Processes background printing. 

FLUSHR 

Periodically flushes disk buf- 
fers. Use for network server 
configuration instead of SGLUSR. 
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Kernel Modules 


Modul e.. .I Eim 


OSNTRY 

Kernel entrypoint module which 
decodes each C-function and 
T-function by number and invokes 
the appropriate kernel module. 

FILMGR 

File manager responsible for 
requests involving local files. 

FILSUP 

File support routines used by 
FILMGR. 

[ FILCOM 

l 

Processes common file-oriented 
requests that are never sent 
over the network. 

FILLOK 

File- and record-level interlock 
routines called by FILMGR. 

FFOMGR 

FIFO management routines called 
by FILLOK. 

I DRVLOK 

Drive interlock routines. 

1 

I FASLOD 

[ 

Program loader incorporating an 
optimizer for fastest loading. 

1 NORLOD 

1 

1 

Unoptimized program loader, an 
alternative to FASLOD. 

1 

| BUFMGR 

I 

1 

[ 

Buffer manager called by FILMGR. 
Maintains pool of disk buffers 
used to speed local file access. 

| DSKMGR 

1 

1 

I 

Disk manager responsible for 
physical access to local disks, 
called by BUFMGR and FASLOD. 

1 

| DSKTBL 
1 

Table defining drives A-P as 
local or remote disk drives. 
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ARCHITECTURE 

Kernel Modules 
(Continued) 


Module 

! function 

NONFIL 

Responsible for functions that 
are not file-oriented. 

CPMSUP 

Processes C-f unctions 7, 8, 24 , 
28, 29, 31, 37 and 107 which are 
rarely used. May be omitted. 

CONMGR 

Responsible for console I/O. 

CONTBL 

Links CONMGR to console driver. 

DO MGR 

Responsible for do-files. 

INPLN 

Console input line editor used 
by CMDINT and C-f unction 10. 

LSTMGR 

Responsible for printer output. 

LSTTBL 

Table defining printers A-P and 
queues A-P as local or remote. 

SPOOLR 

Print spooler which diverts 
print output to a spool file 
when spooling is activated. 

Also handles direct printing to 
remote printers. 

COMMGR 

Responsible for communications 
channel functions. 

NETREQ 

Responsible for issuing network 
request messages for all func- 
tions not processed locally. 

MSGFMT 

Network message format table 
used by NETREQ. 

| NETMGR 

Network message routing routine 
used by NETSVC and NETREQ. 
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ARCHITECTURE 

Kernel Modules 
(Continued) 


Module 

I Function 

NETLOD 

Loads programs over the network. 

RTCMGR 

Real-time clock manager respon- 
sible for maintaining system 
date and time* 

BNKMGR 

Responsible for bank-switching 
and cross-bank linkage in banked 
memory systems. 

DSPCHR 

Multi-task dispatcher which con- 
trols sharing of the local pro- 
cessor among multiple processes. 

DSPS GL 

Null dispatcher used as alterna- 
tive to DSPCHR when only one 
process is required (OSLOAD.COM 
and single-user w/o spooling) • 

MEMMGR 

Memory manager responsible for 
dynamic allocation of memory. 

COMSUB 

Common subroutines used in all 
configurations . 

SYSNIT 

Svstem initialization routine 
executed at system cold-start* 

RTCNUL 

Null real-time clock driver, 
used in configurations where 
there is no periodic interrupt 
source. 

CONREM 

Remote console driver for net- 
work server to support SERVER 
command. 

PATCH 

128 bytes of zeroes, may be in- 
cluded to provide patch area. 
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Driver Modules 


Module 1 

Function 


i 

1 

CONDR0 

Console I/O driver. 


1 

i 

l 

LSTDR0 

Printer output driver (s). 


i 

1 

1 

DSKDR0 

Disk driver (s) . 


1 

1 

| 

CKTDR0 

Network circuit driver (s). 


1 

1 

1 

COMDRV 

Communications channel driver. 


1 

1 

) 

RTCDRV 

Real-time clock driver. 


1 

1 

1 

| 

SELBNK 

Bank-select driver for banked- 
memory systems. 


1 

1 

1 

HDWNIT 

Cold-start initialization for 
all hardware-dependent drivers. 






Standard Packages To simplify the system generation process, 

the most commonly-used combinations of Turbo- 
DOS modules are pre-packaged into the follow- 
ing standard configurations: 

I _ - J £fiSC£jjpfcj-QR I 

I I 

| STDLOADR cold-start loader 1 

j STDSINGL single-user without spooling 1 

I STDS POOL single-user with spooling I 

j STDSERVER network server i 

| STDSLAVE simple user w/o local disks I 

I STDSLAVX complex user with local disks I 


The contents of each standard package is 
detailed in the table on the facing page. 
Most TurboDOS requirements can be satisfied 
by linking the appropriate standard package 
together with a few additional kernel modules 
plus the requisite driver modules. 
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i 

i 

LCLUSR 

1.0 

- 

LCLUSR 

LCLUSR 

LCLUSR 

LCLUSR 

LCLUSR 

i 

i 

LCLMSG 

.3 

- 

LCLMSG 

LCLMSG 

LCLMSG 

LCLMSG 

LCLMSG 

i 

! 
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i 

I 
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- 
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i 

I 

AUTLOD 

• 1 

- 

AUTLOD 

AUTLOD 
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i 
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NONFIL 

NONFIL 

NONFIL 

NONFIL 

NONFIL 

NONFIL 

! 

1 

CON MGR 
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.0 

CONTBL 

CONTBL 

CONTBL 
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.3 

- 

DOMGR 
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DOMGR 

DOMGR 

DOMGR 

1 

I 

INPLN 

.1 

- 

INPLN 

INPLN 

INPLN 

INPLN 

INPLN 

1 

1 

LSTMGR 

.2 

- 

LSTMGR 

LSTMGR 

LSTMGR 

LSTMGR 
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1 

1 

LSTTBL 

.1 

- 

LSTTBL 
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LSTTBL 
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1 

1 
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.5 

- 

- 

SPOOLR 
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SPOOLR 

SPOOLR 

1 

1 

SPLMSG 

.1 

- 

- 
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1 
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.1 
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1 
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- 

MSGFMT 

MSGFMT 

1 

1 

NETMGR 

.6 

- 

- 

- 

NETMGR 

NETMGR 

NETMGR 

1 

1 

NETTBL 
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RTCMGR 
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1 
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.7 

- 

- 
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1 

1 
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.2 
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- 

- 

- 

- 

1 

1 

MEMMGR 

.3 

- 

MEMMGR 

MEMMGR 

MEMMGR 

MEMMGR 

MEMMGR 

! 

1 

COMSUB 

.3 

COMSUB 

COMSUB 

COMSUB 

COMSUB 

COMSUB 

COMSUB 

1 


SISJS1T. 



- 


SYSNIT 

■ sygfliJL 

SYSNIT 

SYSNIT 

1 
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Standard Packages To supplement the modules contained in these 
(Continued) standard packages, the following kernel mod- 

ules may have to be added: 


1 Module I Where Required . __ 1 

| FASLOD 

In non-banked systems with local | 
disks (SINGL/SPOOL/SERVER/USER) . | 

I NETLOD 

In non-banked systems which must | 
load programs over the network j 
from remote disk drives I 
(USER/USERX/sometimes SERVER) . | 

| BNKMGR 

In all banked-memory systems I 

( SINGL/ SPOOL/ SERVER/USER/USERX) . | 

| NETREQ+ 
| MSGFMT 

In network masters (SERVER) which) 
must make requests of other pro- I 
cessors. I 

I NETSVC 

In network users (USER/USERX) I 
which must service requests from I 
other processors, j 

| CPMSUP 

In all systems which require 1 
C-functions 7, 8, 24, 28, 29, 1 
31, 37 and 107 to be supported | 
(SINGL/ S POOL/S ERVER/USER/USERX) . I 

| CONREM 

In network servers (SERVER) that | 
have no console device attached, I 
to allow use of SERVER command j 
(in lieu of console driver), S 

| RTCNUL 

In all configurations which have | 
no RTC driver (including LOADR) . 1 

| PATCH 

In all configurations which re- I 
quire an additional patch area, | 
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Memory Required 


To estimate the memory required by a particu- 
lar TurboDOS configuration, you need to take 
into account the combined size of all func- 
tional modules, driver modules, disk buffers, 
and other dynamic storage. 

Drivers typically require IK to 4K, and can 
be even larger if the hardware is especially 
complex. Disk buffer space should be as 
large as possible for optimum performance, 
especially in a network server. About 4K of 
disk buffer space is reasonable for a single- 
user system, although less can be used in a 
pinch. Other dynamic storage doesn’t usually 
exceed IK in single-user systems, 2K in net- 
work servers. 


The following table gives typical memory 
requirements for standard TurboDOS configura- 


tions on non -banked 

I 

| 0/S 9K 12K 

| Drivers 2K 2K 

1 Buffers 4K 4K 

| Dynamic_IK _JL£ 

! Total 16K 19K 

| TPA - 45K 


In banked-memory sy 
always available. 


hardwar e : 


HqqiI 

SfilvilL 

BSHL 

-USEEX^ 

14K 

18K 

9K 

16K 

2K 

3K 

2K 

2K 

4K 

16K 

- 

4K 

UJC 



2K 

21K 

40 K 

13K 

24K 

43K 

24K 

51K 

40K 


terns, a full 63K TPA is 
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Other Languages 


To facilitate translation into languages 
other than English, TurboDOS has been 
implemented with all textual messages 
segregated into separate modules. All such 
message modules are available in source form 
to TurboDOS licensees upon request. 

The following modules contain all TurboDOS 
operating system messages: 


1 Madame. J contains I 

i I 

I L CL MSG Most operating system messages. | 

I SPLMSG Spooler error messages. I 

I LDRMSG Loader messages for OSLOAD.COM. | 

i I 

In addition, a separate message module is 

available for each TurboDOS command. 
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SYSTEM GENERATION 


Introduction 


This section explains the TurboDOS system 
generation procedure in detail. It describes 
how to use the GEN command to link a desired 
set of TurboDOS modules together, and details 
the numerous system patch points which may be 
modified during system generation. Step-by- 
step procedures and examples are provided. 


The functional modules of TurboDOS are 
distributed in relocatable form (.REL files). 
Hardware-dependent driver modules are fur- 
nished in the same fashion. The TurboDOS GEN 
command is a specialized linker used to bind 
the desired combination of modules together 
into an executable version of TurboDOS. The 
GEN command also includes a symbolic patch 
facility used to modify a variety of opera- 
ting system parameters. 

To generate a complete TurboDOS system, you 
typically must use the GEN command several 
times. At minimum, you have to generate both 
a loader OSLOAD.COM and a server operating 
system 0S5ERVER.SYS. For a networking system 
you also have to generate a user operating 
system OSUSER.SYS. Complex networks may 
require generation of several different user 
or server configurations. Finally, you may 
have to use GEN to generate a cold-start 
bootstrap routine for the start-up PROM or 
boot track. 

At cold-start, the bootstrap routine loads 
the loader program OSLOAD.COM into the TPA of 
the server computer and executes it. OSLOAD 
loads the server operating system from the 
file OS SERVER. SYS into the upper portion of 
memory. The server operating system then 
down-loads the user operating system from 
the file OSUSER.SYS over the network into 
each user computer. 
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The GEN command is a specialized linker for 
software modules in Microsoft relocatable 
format, and is designed primarily for use in 
TurboDOS system generation. 


I GEN srcefile {destfile} {joptions} 


The GEN command links a specified collection 
of relocatable modules together into a single 
executable program. The "srcefile" argument 
specifies the names of two input files: a 
configuration file w sr cef ile.GEN" and a para- 
meter file "sr cef ile.PAR". The "destfile" 
argument specifies the name of the executable 
output file to be created (normally type .COM 
or .SYS) . If "destfile" is omitted, then the 
"srcefile" argument is also used as the name 
of the executable output file, and should 
include an explicit file type (,COM or .SYS), 

If the configuration file "sr cef ile.GEN" is 
found, it must contain the list of reloca- 
table modules ( . REL files) to be linked 
together. If the configuration file is not 
found, then the GEN command operates in an 
interactive mode. You are prompted by an 
asterisk * to enter a series of directives 
from the console. The syntax of each direc- 
tive is: 


I relfile { , relf ile} . . . {;comment} 


A null directive terminates the prompting 
sequence and causes processing to proceed. 

After obtaining the list of modules from the 
file or console, GEN links all of the modules 
together, a two-pass process that displays 
the name of each module as it is encountered. 
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When the linking phase is complete, GEN looks 
for a parameter file "srcef ile.PAJR" and pro- 
cesses it if found. The parameter file (if 
present) must be a text file containing sym- 
bolic patches. The syntax of each .PAR file 
entry is: 


I location « value {, value},., {; comment} | 


where the "value" arguments are to be stored 
in consecutive memory locations starting with 
the address specified by "location". 

The "location" argument may be the name of a 
public symbol, a hexadecimal number, or an 
expression composed of names and hex numbers 
connected by r or - operators. Hex numbers 
must begin with a digit (for example, OFFFF) 
to distinguish them from names. The "loca- 
tion" expression must be followed by an 
equal-sign » character. 

The "value” arguments may be expressions (as 
defined above) or quoted ASCII strings, and 
must be separated by commas, A "value" 
expression is stored as a 16-bit word if its 
value exceeds 255 or if it is enclosed in 
parentheses; otherwise, it is stored as an 8- 
bit byte. A quoted ASCII string may be 
enclosed by either quotes or apostro- 
phes and is stored as a sequence of 8- 
bit bytes. Within a quoted string, ASCII 
control characters may be specified by using 
circumflex (example: "^X" denotes CTRL-X) . 

After the .PAR file (if any) is processed and 
the necessary patches made, GEN writes the 
executable file out to disk. 
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Each relocatable TurboDOS module is magnetic- 
ally serialized with a unique serial number. 
The serial number consists of two components: 
an "origin number” which identifies the 
issuing TurboDOS licensee, and a "unit 
number" which uniquely identifies each copy 
of TurboDOS issued by that licensee. The GEN 
command verifies that all modules to be 
linked are serialized consistently, and 
serializes the executable file accordingly. 


■&£tjpXL J £x£l£J13±i£IL 


;Kxxxx 

Indicates that a system for a 
ban Red-memory environment is to 
be generated, and defines the 
hexadecimal base address "xxxx" 
of the common (nan-switched) 
memory segment. 

;Lxxxx 

Defines the hexadecimal address 
"xxxx" as the lower boundary of 
the executable program. Default 
for .COM files is ;L0100. 

;M 

Prints a load map. 

;s 

Prints a sorted symbol table. 

;Uxxxx 

Defines the hexadecimal address 
"xxxx" as the upper boundary of 
the executable program. Default 
for .SYS files is ;UFFFF . 

;X 

Diagnoses any references to un- 
defined symbols. Default is not 
to diagnose such references, 
since they are quite normal in 
TurboDOS system generation. 
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In the following example, GEN is used to link 
a single-user TurboDOS system for a banked- 
memory system, using the modules listed in 
OSSERVER.GEN and the patches in OSSERVER.PAR, 
creating the executable file OSSERVER. SYS. 


QA } GEN QSSERVER.SYS _;MKCQDD. 

Copyright 1983, Software 2000, Inc. 

* ; Single-user without spooling for 

* ; Advanced Digital Super-Six w/128K 

* STDS INGL /standard single-user pkg. 

* BNKMGR ;banked-memory system 

CPMSUP /seldom-used CP/M functions 

CON192 /console driver 19.2 Kb 

LSTCTS /printer driver CTS protocol 

NITAS6 ; AS6 driver initialization 

INTAS6 /AS6 interrupt handler 

S PDAS 6 ; AS 6 serial/parallel driver 

RTCAS6 ; AS6 real-time clock driver 

DSKAS6 /AS 6 floppy disk driver 

DST58F /disk spec table 5/8 floppy 

BNKAS6 /AS 6 bank-select driver 


Pass 1 

LCLUSR LCLTBL CMDINT AUTLOD SGLU3R etc. 
Pass 2 

LCLUSR LCLTBL CMDINT AUTLOD SGLUSR etc. 

Processing parameter file; 

; Patches for single-user w/'o spooling 
AUTUSR - 80 /logon to user 0 privileged 
NMBUFS - 8 /number of disk buffers 
PTRAST = 2 /printer on channel 2 
EOPCHR = " A Z" /end-of-print character 
SRHDRV = 1 /search drive A 
PRTMOD = 0 /direct printing mode 


Writing output file A :OSS ERVER. SYS 
0A} 
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Error Messages i 

I File name missing from command 
i Invalid input file name 
I Serial number violation 
I Not enough memory 
I Vacuous input file(s) 

I Unexpected EOF in input file 
I Disk is full 
I Can't make output file 
I No input files 
I Can't open input file 
j Load address out-of-bounds 
| Multiple defined starting address 
I Duplicate symbol: <name> 

I Undefined symbol: <name> 
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The following table describes 45 public sym- 
bols in TurboDOS which you may wish to modify 
using the symbolic patch facility of the GEN 

command. Patch points for the North Star 

drivers are given in the Appendix. 

I BifMliIxaLifi. ! 

I I 

| ABTCHR = " A C" CONTBL i 

I I 

| Abort character (after attention) . I 


ATNBEL = " A G" CONTBI* 

Attention- received warning character. 


ATNCHR = "~S" CONTBL | 

Attention character. Nay be patched to | 
another character if the default value of | 
CTRL-S is needed by application programs. I 
A common choice is zero (NUL) , which al- | 
lows the console BREAK key to be used as i 
an attention key. I 


AUTUSR = OFF AUTLOG 

Automatic log-on user number. Default 
value of OFF requires that user log-on. 

If you do not want to have to log on, 
patch AUTUSR to the desired user 
number (00-1F) , and set the sign-bit 
if a privileged log-on is desired. 
Generally patched to 80 in single-user 
systems to cause automatic privileged 
log-on to user zero. 
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BFLDLY = ( 012C) FLUSHR 

Buffer flush delay determines how often 
disk buffers are written to disk r stated 
in system "ticks". Default value (300 
decimal) causes buffers to be flushed 
about every five seconds (assuming 60 
ticks per second) . 


BUFSIZ - 3 BUFMGR 

Default disk buffer size (0=128 r 1=256, 
2=512, 3=lK, . . . , 7=16K) . Default value 
specifies IK disk buffers. 


CKTAST = (0000) ,CKTDRA, NETTBL 

(0100) , CKTDRB , 

(0200) , CKTDRC, 

(0300) , CKTDRD 

Circuit assignment table defines network 
topology. Contains NMBCKT two-word en- 
tries, one for each network circuit to 
which this processor is attached. The 
first word of each entry specifies the 
network address by which this processor 
is known on a particular circuit, and the 
second word specifies the entrypoint ad- 
dress of the circuit driver responsible 
for that circuit. (Possibly several cir- 
cuits may be handled by the same driver.) 


CLBLEN = 9D CMDINT 

Command line buffer length defines long- 
est permissible command line. The de- 
fault value permits two 80-char lines. 
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CLPCHR » CMDINT 

Command line prompt character. 


CLSCHR = ”\ w CMDINT 

Command line separator character. 


COLDFN * 0 , "COLDS TRT" , "AUT" AUTLOD 

File name and drive for cold-start auto- 
load processing (in FCB format) . 


COMPAT = 0 FILLOK 

Default compatibility flags which define 
rules to be used for file-sharing. Patch 
to QF8 to relax most MP/M restrictions. 


CONAST = 0 , CONDRA CONTBL 

Console assignment table defines how con- 
sole I/O is handled. First byte passed 
to console driver, and commonly defines 
the channel number (e.g., serial port) to 
be used for the console. Following word 
specifies the entrypoint address of the 
console driver to be used. 


CPMVER = 31 NONFIL 

CP/M BDOS version number returned by 
C-f unction 12 in L-register. 
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CURBNK = 1 BNKMGR 

Initial memory bank selected for TPA at 
cold-start. Applicable to banked-memory 
systems only. Patch to 0 to select non- 
banked mode at cold-start. 


DEFDID = (0000) NETTBL 

Default network destination ID, used for 
routing all network requests that are not 
related to a particular disk drive, queue 
or printer. In a user, DEFDID should be 
set to the network address of the server. 


DSKAST = 0 0 , DSKDRA, 01 , DSKDRB, DSKTBL 

OFF, (0000) , OFF, (0000) , . . . 

Disk assignment table, an array of 16 
three-byte entries (one for each drive 
letter A-P) that defines which drives are 
local, remote, and invalid. 

For a local drive, the first byte must 
not have the sign-bit set. That byte is 
passed to the disk driver, and is common- 
ly used to differentiate between multiple 
drives connected to a single controller. 
The following word specifies the entry- 
point address of the disk driver to be 
used. 

For a remote drive, the first byte must 
have the sign-bit set. The low-order 
bits of that byte specify the drive let- 
ter to be accessed on the remote proces- 
sor. The following word specifies the 
network address of the remote processor. 
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DSKAST (Continued) DSKTBL 

For an invalid drive, the first byte must 
be OFF, and the following word should be 
( 0000 ) . 

NOTE: In user configurations STDS LAVE 

and STDSLAVX, the default values are: 

DSKAST = 80, (0000) ,81, (0000) , 

82 , (0000) ,83 , (0000) , 

. . . ,8E, (0000) , 8F , (0000) 


| DSPPAT = 01,01,01,. ..,01 LSTTBL 

I De-spool printer assignment table, an ar- 
| ray of 16 bytes (one for each printer 
j letter A-P) that defines the initial 
| queue to which each printer is assigned. 

[ Hex values 01 through 10 correspond to 
j queues A-P, and 0 means that the printer 
| is off-line. The default value assigns 
| all printers to queue A. 


ECOCHR - " A P n CONTBL 

Echo-print character (after attention) . 


EOPCHR = 0 LSTTBL 

End-of-print character. May be patched 
to any non-null character, in which case 
the presence of that character in the 
print output stream will automatically 
signal an end-of-print- job condition. 

The value zero disables this feature. 
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FWDTBL = (OFFFF ) f (OFFFF) , (OFFFF) , 
( OFFFF) , OFF 


NETTBL 


Network forwarding table f an array of 
two-byte entries that define any explicit 
message forwarding routes to be used by 
this processor* The first byte of each 
entry specifies a "foreign" circuit num- 
ber N, and the second byte a "domestic" 
circuit number C* Any messages destined 
for circuit N will be routed via circuit 
C* This table is variable-length, termi- 
nated by OFF , and defaults to empty. 


LDCOLD = OFF 


AUTLOD 


Cold-start autoload enable flag. Patch 
to zero if you want to disable the cold- 
start autoload feature (COLDSTRT. AUT) . 


LDWARM = OFF 


AUTLOD 


Warm-start autoload enable flag. Patch 
to zero if you want to disable the warm- 
start autoload feature ( WARMS TRT. AUT) . 


LOADFN = 0, "OSSERVER", "SYS" 


OSLOAD 


Default file name and drive (in FCB for- 
mat) loaded by OSLOAD.COM. Drive field 
(FCB byte 0) may be patched to an expli- 
cit drive value to inhibit scanning. 
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1- Module, i 

LOGUSR = IF FILCOM 


User number for logged-off state, 
fault value is 31 decimal. 


De- 


MEMBLL - (1103) 


MEMMGR 


Memory base lower limit, prevents alloca- 
tion of dynamic memory space below this 
address under any circumstances. Default 
value guarantees minimum of 4K TPA (which 
is enough for BUFFERS command) . 


MEMRES - (0100) 


LCLUSR 


Memory reserve, used when loading a pro- 
gram into TPA to provide a safety margin 
between the base of dynamic memory space 
and the top of TPA. This allows dynamic 
space to grow by the amount of MEMRES 
before it encroaches on the TPA (and pos- 
sibly causes a crash) . The MEMRES value 
may have to be increased above the 256- 
byte default value for reliable operation 
particularly in network servers. 


MEMTOP = ( OFFFF) 


OSLOAD 


Top of memory address for purposes of the 
RAM diagnostic test performed by OSLOAD. 
Patch to (0000) to omit test altogether. 


NMBCKT = 1 


NETTBL 


Number of network circuits to which this 
processor is connected. 
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N MB MBS * 0 NETMGR 

Number of message buffers pre-allocated 
at cold-start. Message buffers are allo- 
cated dynamically as needed, but this may 
cause fragmentation which prevents you 
from obtaining more TPA by reducing the 
size of the disk buffer pool. If this is 
important, patching NMBMBS to a suitable 
positive value will eliminate the problem 
(twice the number of network nodes is a 
good starting value to try) . 


j NMBRPS = 0 NETMGR j 

| Number of reply packets pre-allocated at | 
j cold-start. Reply packets are allocated I 
j dynamically as needed, but this may cause | 
| fragmentation which prevents you from ob- | 
| taining more TPA by reducing the size of j 
| the disk buffer pool. If this is impor- I 
| tant, patching NMBRPS to a suitable posi- j 
| tive value will eliminate the problem. i 
j (The number of network nodes is a good I 
] starting value to try.) I 


N MB SVC = 2 NETSVC 

Number of network server processes to be 
activated. (The number of network nodes 
is a good starting value to try.) 
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NMBUFS = 4 


BUFMGR 


Default number of disk buffers allocated 
at cold-start. Must be at least 2. For 
optimum performance, allocate as many 
buffers as possible (consistent with TPA 
and other memory requirements) , 


PRTCHR = 


'L" 


CONTBL 


End-print character (after attention) . 
This is a console attention-response, not 
to be confused with EOPCHR. 


PRTMOD 


LCLTBL 


Initial print mode for local user. The 
default value of 1 specifies spooling. 
Patch to 0 for direct, or 2 for console. 


PTRAST = 00,LSTDRA,0FF, (0000) , LSTTBL 

OFF, (0000) , OFF , (0000) , . . . 

Printer assignment table, an array of 16 
three-byte entries (one for each printer 
letter A-P) that defines which printers 
are local, remote, and invalid. 

For a local printer, the first byte must 
not have the sign-bit set. That byte is 
passed to the disk printer and com- 
monly defines the channel number (e.a., 
serial port) to be used for the printer. 
The following word specifies the entry- 
point address of the printer driver to be 
used. 
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PTRAST (Continued) LSTTBL 

For a remote printer, the first byte must 
have the sign-bit set. The low-order 
bits of that byte specify the printer 
letter to be accessed on the remote pro- 
cessor. The following word specifies the 
network address of the remote processor. 

For an invalid printer, the first byte 
must be OFF, and the following word 
should be (0000) . 

NOTE: In user configurations STDSLAVE 

and STDSLAVX, the default values are: 

PTRAST = 80, (0000) ,81, (0000) , 

82, (0000) ,83,(0000) , 

. . ,,8E, (0000) ,8F, (0000) 


QUEAST = 00, (0000) , OFF, (0000) , LSTTBL 

off, (oooo) , off , (oooo) , . . . 

Queue assignment table, an array of 16 
three-byte entries (one for each queue 
letter A-P) that defines which queues are 
local, remote, and invalid. 

For a local queue, all three bytes must 
be set to zero. 

For a remote queue, the first byte must 
have the sign-bit set. The low-order 
bits of that byte specify the queue let- 
ter to be accessed on the remote proces- 
sor. The following word specifies the 
network address of the remote processor. 
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QUEAST (Continued) LSTTBL 

For an invalid queue, the first byte must 
be OFF, and the following word should be 
( 0000 ) . 

NOTE: In user configurations STDSLAVE 

and STDSLAVX, the default values are: 

QUEAST = 80, (0000) ,81, (0000) , 

82,(0000) ,83 ,(0000) , 

. *.,8E, (0000), 8F, (0000) 


QUEPTR = 1 LCLTBL 

Initial queue or printer assignment. If 
PRTMOD = 1 (spooling), QUEPTR specifies a 
queue assignment. If PRTMOD = 0 (direct) 
QUEPTR specifies a printer assignment. 

In both cases, hex values 01 through 10 
correspond to letters A-P, and zero means 
do not queue or print off-line. 


RESCHR = "~Q" CONTBL 

Resume character (after attention) • 


SCANDN = 0 OSLOAD 

Scan direction flag for OSLOAD. Patch to 
0FFH to scan P-to-A (instead of A-to-P) . 


SLVFN = "OSUSER n ,"SYS" NETSVC 

Name and type of file (in FCB format) to 
be down-loaded into user processors. 
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S PL DRV = OFFH LCLTBL 

Initial spool drive. Default value OFF 
indicates spool to system disk (disk from 
which TurboDOS was loaded at cold-start) . 
Patch to 0 through F to specify a parti- 
cular drive A-P. 


SRHDRV = 0 CMDINT 

Search drive for command files. Patch to 
hex value 01 through 10 to search drive 
A-P if command is not found on current 
(default) drive. Patch to OFF to search 
system disk (disk from which TurboDOS was 
loaded at cold-start) . Default value 0 
disables this feature altogether. 


SUBFN = 0,"$$$ ” t "SUB ” SUBMIT 

Submit file name searched for by optional 
CP/M submit-file emulator. 


WARMFN = 0, "WARMS TRT", "AUT" AUTLOD 

File name and drive for warm-start auto- 
load processing (in FCB format). 
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Network Operation TurboDOS accomodates a wide variety of net- 
work topologies, ranging from the simplest 
point-to-point server/user networks to the 
most complex star, ring, and hierarchical 
structures. The physical implementation of 
network topologies involves adding communi- 
cations hardware and software and writing 
new network drivers. 


Network Model A TurboDOS network is defined to consist of 

up to 255 with up to 255 nodes 
(processors) on each circuit. Each node has 
a unique 16-bit ne t wor k address consisting of 
an 8-bit circuit number plus an 8-bit node 
number (on that circuit). 

Any processor may be connected to several 
circuits, if desired. A processor connected 
to multiple circuits has multiple network 
addresses, one for each circuit. Such a 
processor even may be set up to perform mes- 
sage forwarding from one circuit to another, 
permitting dialogue between network nodes 
that do not share a common circuit between 
them (more on this later) . 


Network Tables The actual network topology is defined by a 

series of tables in each processor. The 
tables are set up during system generation, 
and define the network as "seen" from the 
viewpoint of each processor. The tables are: 


D£S£X±2±±9n 

NMBCKT A byte value that defines the 
number of network circuits to 
which this processor is connec- 
ted. 
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1 Description 

CKTAST 

The circuit assignment table 
containing NMBCKT entries defin- 
ing the network address by which 
this processor is known on each 
circuit, and specifying the net- 
work circuit driver responsible 
for each handling each circuit. 

DSKAST 

The disk assignment table that 
specifies for all drive letters 
A-P which are local, remote, and 
invalid. This table specifies 
a network address for each re- 
mote drive, and a disk driver 
for each local drive. 

PTRAST 

The printer assignment table 
that specifies for all printer 
letters A-P which are local, re- 
mote, and invalid. This table 
specifies a network address for 
each remote printer, and a prin- 
ter driver for each local prin- 
ter . 

QUEAST 

The queue assignment table that 
specifies for all queue letters 
A-P which are local, remote, and 
invalid. This table specifies a 
network address for each remote 
queue. 

DEFDID 

The default network destination 
ID, used for routing all network 
requests that are not related to 
a specific disk drive, printer, 
or queue. 
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FWDTBL The message forwarding table 
that specifies any additional 
circuits (not directly connected 
to this processor) which may be 
accessed via explicit message 
forwarding, and how messages 
destined for such circuits are 
to be routed. 


These tables are pre-defined with default 
values to make set-up of simple server/user 
networks very easy. For complex multi- 
circuit networks, the set-up is somewhat more 
complicated (as might be expected). 

Refer to the preceding Rsti JPJLfi sub- 
section for details of the organization and 
defaults for these network tables. 
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The network architecture of TurboDOS supports 
two kinds of message forwarding: "implicit” 
and "explicit". To understand the distinc- 
tion, consider the case of a network with 
three processors (PI, P2, and P3) connected 
by two circuits (Cl and C2) as follows: 


II II II 

I PI 1 Cl i P2 | C2 I P3 | 


A program running in PI makes an access to 
drive D. Suppose the disk assignment tables 
in the three processors are set up in the 
following fashion: 

. Pi's DSKAST defines its drive D as a 
remote reference to P2's drive B. 

. P2's DSKAST defines its drive B as a 
remote reference to P3's drive A. 

. P3's DSKAST defines its drive A as a 
local device attached directly to P3. 

In this case. Pi's access to its drive D 
actually winds up implicitly accessing P3*s 
drive A. This is implicit forwarding. 

Alternatively, suppose Pi's DSKAST defines 
its drive D as a remote reference to P3's 
drive A, and that Pi's FWDTBL provides that 
messages destined for circuit C2 may be 
routed via Cl. In this case, Pi sends a 
request to P3 on circuit Cl. P2 receives the 
request, recognizes that it should be forwar- 
ded, and retransmits the request to P3 via 
circuit C2. Thus, PI accesses P3's drive A 
with the assistance of P2, but this time PI 
is not aware of P2 f s role in the transaction. 
This is explicit forwarding. 
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Let's take a reasonably complex network situ- 
ation and see how to construct the required 
.GEN and .PAR files. 


Our hardware is an S-100 microcomputer system 
consisting of a Z80 CPU board, a 64K memory 
board, hard disk and floppy disk controller 
boards (all these make up the server proces- 
sor), and several single-board user proces- 
sors on the same bus. The server processor 
is interfaced to two printers, one daisywheel 
and the other matrix, via RS232 serial ports. 
The daisywheel printer is on serial port 0 
and uses XON/XOFF protocol, while the matrix 
printer is on port 1 and uses cl ear- to-send 
handshaking. In addition, the server has a 
high-speed RS422 interface connecting it to 
another S-100 system of similar configuration 
some distance away. 


We want to configure a TurboDOS system for 
this hardware that permits all of the users 
of each S-100 system to access the hard disk, 
floppy disks, and printers attached to both 
the local and remote S-100 system. We might 
create the following OSSERVER.GEN file: 


; OSSERVER.GEN for complex example 
STDSERVER ; standard server package 
FASLOD ; non-banked program load 

NETREQ ; to make requests of other sys 

MSGFMT ; needed by NETREQ 

CONREM ; no console on the server 

LSTXON ; XON/XOFF for daisy (LSTDRA) 

LSTCTS ; CTS for matrix (LSTDRB) 

DSKHDC ; hard disk controller (DSKDRA) 

DSKFDC ; floppy disk control. (DSKDRB) 

CKTSLV ; circuit driver for users (CO) 

CKT422 ; circuit driver for RS422 (Cl) 

RTCDRV ; real-time clock driver 

NITDRV ; hardware initialization driver 
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SYSTEM GENERATION 

A Complex Example 
(Continued) 


Our system generation task is completed by 
creating the companion OSSERVER.PAR file: 


OSSERVER.PAR for complex example 


NMBCKT 

CKTAST 


= 2 


DSKAST = 


(0000) ,CKTDRA 
(0100) , CKTDRB 


2 net circuits 
ckt 0 for users 
ckt 1 via RS422 


PTRAST 


QUEAST = 


DEFDID 

DSPPAT 

MEMRES 

NMBMBS 

NMBRPS 

NMBSVC 

NMBUFS 


00 , DSKDRA 

00 , DSKDRB 

01 , DSKDRB 
80 , (0101) 
81, (0101) 
82, (0101) 

00 , LSTDRA 

01 , LSTDRB 
80,(0101) 
81, (0101) 
00 , ( 0000 ) 
00 ,( 0000 ) 
80,(0101) 
81, (0101) 
( 0101 ) 
1 , 2 , 3, 4 
(0400) 

0A 

5 

5 

14 


drv A is local HD 
drv B is local FD0 
drv C is local FDl 
drv D is remote HD 
drv E is remote FD0 
drv F is remote FDl 
ptr A is lcl daisy 
ptr B is lcl matrix 
ptr C is rmt daisy 
ptr D is rmt matrix 
queue A is local 
queue B is local 
queue C is remote A 
queue D is remote B 
default other server 
assgn ptrs to queues 
IK safety margin 
10 message buffers 
5 reply packets 
5 server processes 
20 IK disk buffers 


The generation of the second server operating 
system could be identical, except that all 
occurrences of network addresses (0100) and 
(0101) in the OSSERVER.PAR file would be 
reversed. Generation of the user operating 
system would be very straightforward, and 
identical for both systems. 

If you study this example thoroughly until 
you understand the reason for every .GEN and 
.PAR file entry, you should have little 
trouble setting up your own "sysgens". 


2-24 




TurboDOS 1.3 280 
Implementor 1 s Guide 


Sysgen Procedure 


SYSTEM GENERATION 
Sysgen Procedure 


To conclude this section, here is a suggested 
step-by-step procedure for generating a new 
version of TurboDOS, if you are not using 
the North Star CONFIG program. 

1. Bring up a previous version of TurboDOS. 
If this is your first attempt to generate 
a TurboDOS system, you may bring up CP/M 
instead. However, if you are using CP/M, 
all disks will have to be in a format 
compatible with both CP/M and TurboDOS. 

2. Make a working copy of your TurboDOS dis- 
tribution disk. Do not use the original 
disk (in case something goes wrong) . 
Insert the working diskette in a conven- 
ient disk drive. 

3. Using your favorite text editor, create or 
revise the file OSS ERVER. GEN containing 
the names of the relocatable modules to be 
linked together. Generally, this will 
consist of the appropriate STDxxxxx stan- 
dard package plus selected additional 
modules and all required device drivers. 

4. Using your editor once again, create or 
revise the file OSSERVER.PAR containing 
any required patches. This may be omitted 
if no patches are desired. 

5. For HORIZON servers use the command 
GEN OSSERVER. SYS ? UE7FF to generate an 
executable system in accordance with the 
.GEN and .PAR files just constructed. If 
your hardware has banked memory, don't 
forget to use the ;Kxxxx option. 
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(Continued) 


6. Construct a user operating system in the 
same manner. Create or revise the files 
OSUSER-A. GEN and OSUSER-A. PAR, then use 
the command GEN QSUSER'.’SYS to generate 
the down-loadable user operating system. 

7. To test the newly-generated system, eject 
all disks other than your working disk 
(again, in case something goes wrong) . 
Reset the HORIZON. The new system should 
cold-start. If it fails to come up or to 
function properly, you will have to start 
over at step 1 and check your work 
carefully — there is most likely an error 
in one of your .GEN or .PAR files, or a 
’’bug” in one of your drivers. 



Sysgen Procedure 
(Continued) 
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DISTRIBUTION This section explains the TurboDOS distribu- 

tion procedure in detail. It covers TurboDOS 
licensing requirements, and the obligations 
of licensed distributors, dealers, and end- 
users. It describes how to make up and 
serialize TurboDOS distribution disks. 

Although this section is of concern primarily 
to licensed TurboDOS distributors, we've 
included it here so that dealers and end- 
users can gain a better perspective on the 
overall distribution process. 


TurboDOS Licensing TurboDOS is a proprietary software product of 

Software 2000, Inc. As such, it is protected 
by law against unauthorized use and reproduc- 
tion. Authorization to use and/or reproduce 
TurboDOS is granted only by written license 
agreement . 


Legal Protection TurboDOS programs and documentation are copy- 
righted, which means it is against the law to 
make copies without express written authori- 
zation from Software 2000 to do so. 

The word "TurboDOS" is a trademark owned by 
Software 2000 and registered in Class 9 (com- 
puter software) and Class 16 (documentation) 
with the trademark offices of the United 
States and most of the developed countries of 
the free world. This means it is against the 
law to make use of the TurboDOS trademark 
without express written authorization from 
Software 2000. 

Software 2000 has licensed certain companies 
to distribute TurboDOS. Such distributors 
are authorized to use the TurboDOS trademark, 
and to reproduce, distribute, and sub-license 
TurboDOS programs and documentation to deal- 
ers and end-users. 
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TurboDOS Licensing 
(Continued) 


TurboDOS may be used only after the user has 
paid the required license fee, signed a copy 
of the TurboDOS end-user license agreement, 
and returned the signed agreement to the 
issuing TurboDOS distributor. Then, TurboDOS 
may be used only in strict conformance with 
the terms of the license. 

Each end-user license allows TurboDOS to be 
used on one specific computer system identi- 
fied by make, model, and serial number. The 
end-user license may not be transferred from 
one computer system to another, and expressly 
forbids copying programs and documentation 
except as required for backup purposes only. 

A separate license fee must be paid and a 
separate license signed for each computer 
system on which TurboDOS is used. Network 
user computers that cannot operate stand- 
alone (because, for example, they have no 
local disk) do not have to be licensed sepa- 
rately from the network server. However, 
networked computers that are also capable of 
stand-alone operation under TurboDOS must 
each be licensed separately (whether or not 
they are actually used stand-alone) . 


A dealer must sign a TurboDOS dealer agree- 
ment and return the signed agreement to the 
issuing distributor. Then, the dealer is 
permitted to purchase pr e-serial ized copies 
of TurboDOS programs and documentation from 
the distributor, and to resell them to end- 
users. Dealers may not make copies of 
TurboDOS programs or documentation for any 
purpose whatever. 

Before delivering each copy of TurboDOS, the 
dealer must see to it that the end-user signs 
the TurboDOS end-user license agreement and 
returns it to the issuing distributor. 
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(Continued) 


Each licensed TurboDOS distributor is provi- 
ded a server copy of TurboDOS relocatable 
modules and command programs on diskette. A 
distributor is allowed to reproduce and 
distribute copies of TurboDOS to dealers and 
end-users, but only in connection with 
certain specifically authorized hardware 
(usually manufactured or sold by the distri- 
butor). The distributor is required to 
serialize each copy of TurboDOS with a unique 
sequential magnetic serial number, and to 
register each serial number promptly with 
Software 2000. (Serialization is described 
in more detail below.) 

Each distributor is also provided with a 
master copy of TurboDOS documentation, either 
in camera-ready hardcopy or in ASCII files on 
disk. The distributor is responsible for 
reproducing the documentation and furnishing 
it with each copy of TurboDOS it issues. 

A distributor must require each dealer to 
sign and return a TurboDOS dealer agreement 
before issuing copies of TurboDOS to the 
dealer for resale. A distributor must 
require each end-user to sign and return a 
TurboDOS end-user license agreement before 
issuing a copy of TurboDOS directly to the 
end-user. 
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TurboDOS Licensing 
(Continued) 


Each copy of TurboDOS is magnetically serial- 
ized with a unique serial number. Such 
serialization helps ensure that reproduction 
and distribution of TurboDOS is done in 
strict accordance with the required licensing 
and registration procedures, and facilitates 
tracing of unlicensed copies of the software. 

Each relocatable module of TurboDOS distribu- 
ted to a dealer or end-user has a magnetic 
serial number composed of two parts: 

• an origin num ber that identifies the 
issuing distributor, and 

. a sequential unit number that uniquely 
identifies each copy of TurboDOS issued 
by that distributor. 

During system generation, the GEN command 
verifies that all modules making up a Turbo- 
DOS configuration are serialized consistent- 
ly, and magnetically serializes the resulting 
executable version of TurboDOS accordingly. 

The relocatable modules on the master disk 
furnished to each licensed TurboDOS distribu- 
tor are partially serialized with an origin 
number only. Each distributor is provided a 
serialization program (SERIAL.COM) that must 
be used to add a unique sequential unit num- 
ber to each copy of TurboDOS issued by the 
distributor. The GEN command will not accept 
partially-serialized modules that have not 
been serialized with a unit number. Con- 
versely, the SERIAL command will not re- 
serialize modules that have already been 
fully serialized. 
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TurboDOS Licensing 
(Continued) 


Software 2000 maintains telephone and telex 
"hot-lines" to provide TurboDOS technical 
assistance to its distributors. These are 
unlisted numbers providing direct access to 
the authors of the TurboDOS operating system, 
and are furnished only to licensed TurboDOS 
distributors. We encourage distributors to 
take advantage of this service whenever tech- 
nical questions or problems arise in using or 
configuring TurboDOS. 

It is the responsibility of each licensed 
distributor to provide technical support to 
its dealers and end-user customers. Software 
2000 Cflfln p t assist dealers or end-users 
directly. Where exceptional circumstances 
seem to require direct contact between Soft- 
ware 2000 technical personnel and a dealer or 
end-user, this must be handled strictly by 
prior arrangement between Software 2000 and 
the distributor. 


3-5 




TurboDOS 1.3 Z80 
Implementor's Guide 


SERIAL Command 


Syntax 


Explanation 


Options 


DISTRIBUTION 
SERIAL Command 


The SERIAL command enables TurboDOS distribu- 
tors to magnetically serialize relocatable 
modules of TurboDOS for distribution. 


I SERIAL srcefile destfile ;Unnn {options} I 
I SERIAL ;Unnn {options} I 


The SERIAL command works exactly like the 
COPY command, and accepts exactly the same 
arguments and options. However,- SERIAL has 
the additional function of magnetically 
serializing relocatable modules as they are 
copied. SERIAL serializes files of type .REL 
(Z80 modules) and type .0 (8086 modules). 
Other files are copied without any change. 

The unit number must be specified on the 
command line as ;Unnn, where "nnn" represents 
a decimal unit number in the range 0-65535. 
Unit numbers must be assigned sequentially, 
starting with 1. Unit number 0 is reserved 
by convention for in-house use by the distri- 
butor . 

SERIAL produces fully-serialized modules that 
are encoded with the distributor's origin 
number and the specified unit number. GEN 
does not accept TurboDOS modules unless they 
have been fully serialized in this fashion. 


Option 1. Explanation 

SERIAL accepts all COPY options, plus: 

;Unnn Relocatable modules (type .REL 
or .0) are magnetically serial- 
ized with unit number nnn, which 
must be a decimal integer in the 
range 0 to 65535. This "option" 
is mandatory for SERIAL. 
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(Continued) 


OA} SERIAL 

*.REL 

B: :U289N 



OA: AUTLOD 

.REL 

copied 

to 

OB: AUTLOD. 

REL 

OAsAUTLOG 

.REL 

copied 

to 

OBsAUTLOG. 

REL 

OAsSYSNIT. 

OA} 

REL 

copied 

to 

0B:SYSNIT. 

REL 


SERIAL incorporates all COPY error mes- 
sages, plus: 

Unit number not specified 
Origin number violation 
File is already serialized 
Unexpected EOF in .0 or .REL file 
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DISTRIBUTION 
PACKAGE Command 


The PACKAGE command lets you combine any 
collection of relocatable modules into a 
single concatenated .REL file. 


I PACKAGE srcefile {destfile} 


PACKAGE may be used to construct custom 
packages of TurboDOS modules, make additions 
or changes to the supplied STDxxxxx packages, 
pre-package collections of driver modules, 
and so forth. 

The "srcefile" argument specifies the name of 
an input file "srcef il e.PKG " that lists the 
modules to be packaged. The "destfile" argu- 
ment specifies the name of the concatenated 
.REL file to be created. If "destfile" is 
omitted, then the "srcefile" argument is also 
used as the name of the output .REL file. 

If the .PKG file is found, it must contain 
the list of relocatable modules (.REL files) 
to be linked together. If the configuration 
file is not found, then the PACKAGE command 
operates in an interactive mode. You are 
prompted by an asterisk * to enter a series 
of directives from the console. The syntax 
of each directive is: 


i relfile { , relf ile} . . . {;comment} 


A null directive terminates the prompting 
sequence and causes processing to proceed. 

After obtaining the list of modules from the 
file or console, PACKAGE concatenates all of 
the modules together (displaying the name of 
each module as it is encountered) and writes 
the result to the output file. 
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(Continued) 


0 A } g ACKAfiB J5TDLQ ABB 

* ? STDLOADR. PKG standard loader package 

* OSLOAD, LDRMSG , OSNTRY, FILMGR, FILSUP 

* F ILCOM , B U FMGR , DS KMGR , DSKTBL, NON F IL 

* CONMGR, CONTBL , DSPSGL , COMSUB 

OSLOAD LDRMSG OSNTRY FILMGR FILSUP etc. 
OA} 


File name missing from command 
Invalid input file name 
Unexpected EOF in input file 
Disk is full 
Can't make output file 
Can't open input file 
No input files 
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Here is the procedure to be followed by dis- 
tributors when creating each copy of TurboDOS 

to be issued to a dealer or end-user: 

1. Assign a unique sequential unit number for 
this copy of TurboDOS, and register it 
immediately by filling out a serial number 
registration card (or agreed-to substi- 
tute) and mailing to Software 2000, Inc* 

2. Format a new disk, and label it with the 
following information clearly legible: 

• trademark TurboDOS™ 

. version number (1.3x) 

. origin and unit numbers (oo/uuuu) 

• statutory copyright notice: 

Copyright 198x by Software 2000, Inc. 
All rights reserved. 

3. Use the SERIAL command to copy and serial- 
ize the appropriate files from your dis- 
tribution master disk to the new disk. 
Use the tables on the following page to 
guide you in determining what files to put 
on the new disk. 

IMPORTANT NOTE: Be absolutely certain 

that the new disk does not contain any 
unserialized modules or SERIAL.COM! 

4. Using the new serialized disk, use the GEN 
command to generate an executable loader 
and operating system. Follow the system 
generation procedure described in the 
previous section. 

5. In addition to the serialized disk, you 
should issue copies of TurboDOS documenta- 
tion and a start-up PROM (if applicable). 
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Distrib. Procedure 
(Continued) 


The following table may be used for guidance 
in preparing TurboDOS disks for distribution. 
In addition to the files shown, you need to 
include hardware-dependent driver modules and 
utility programs as appropriate. 


single-user | single-user J multi-user 

xjLsl spo oler 1 netwgrJsiiig. 


STDLOADR • REL 
STDS INGL. REL 


FASLOD .REL 
BNKMGR .REL 
CPMSUP .REL 
RTCNUL .REL 
PATCH .REL 
SUBMIT .REL 
OSBOOT .REL 


AUTOLOAD.COM 
BACKUP .COM 
BANK . COM 

BOOT . COM 
BUFFERS .COM 

COPY . COM 
DATE . COM 
DELETE .COM 
DIR .COM 
DO . COM 
DRIVE .COM 


STDLOADR. REL 
STDS INGL. REL 
STDSPOOL . REL 


FASLOD .REL 
BNKMGR .REL 
CPMSUP .REL 
RTCNUL .REL 
PATCH .REL 
SUBMIT .REL 
OSBOOT .REL 


AUTOLOAD.COM 
BACKUP .COM 
BANK . COM 

BOOT .COM 
BUFFERS .COM 

COPY . COM 
DATE . COM 
DELETE . COM 
DIR .COM 
DO . COM 
DRIVE .COM 


STDLOADR 

.REL 

STDS INGL 

.REL 

STDSPOOL 

.REL 

STDMASTR 

.REL 

STDSLAVE 

.REL 

STDSLAVX 

.REL 

FASLOD 

.REL 

BNKMGR 

.REL 

CPMSUP 

.REL 

RTCNUL 

.REL 

PATCH 

.REL 

SUBMIT 

.REL 

OSBOOT 

.REL 

NETLOD 

.REL 

NETREQ 

.REL 

MSGFMT 

.REL 

NETSVC 

.REL 

CONREM 

.REL 

AUTOLOAD 

.COM 

BACKUP 

.COM 

BANK 

.COM 

BATCH 

.COM 

BOOT 

.COM 

BUFFERS 

.COM 

CHANGE 

.COM 

COPY 

.COM 

DATE 

.COM 

DELETE 

.COM 

DIR 

.COM 

DO 

.COM 

DRIVE 

.COM 
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single-user | 
w/o spooler 1 

single-user 
with spooler 

multi-user 
networking _ 


DUMP 

.COM 

DUMP 

.COM 

DUMP 

.COM 


ERASEDIR 

.COM 

ERASEDIR 

.COM 

ERASEDIR 

.COM 


- 


- 


FIFO 

.COM 


FIXDIR 

.COM 

FIXDIR 

.COM 

FIXDIR 

.COM 


FIXMAP 

.COM 

FIXMAP 

.COM 

FIXMAP 

.COM 


FORMAT 

.COM 

FORMAT 

.COM 

FORMAT 

.COM 


GEN 

.COM 

GEN 

.COM 

GEN 

.COM 


LABEL 

.COM 

LABEL 

.COM 

LABEL 

.COM 


- 


- 


LOGOFF 

.COM 


- 


- 


LOGON 

.COM 


- 


- 


MASTER 

.COM 


PRINT 

.COM 

PRINT 

.COM 

PRINT 

.COM 


- 


PRINTER 

.COM 

PRINTER 

.COM 


- 


QUEUE 

.COM 

QUEUE 

.COM 


- 


- 


RECEIVE 

.COM 


RELCVT 

.COM 

RELCVT 

.COM 

RELCVT 

.COM 


RENAME 

, COM 

RENAME 

.COM 

RENAME 

.COM 


- 


- 


SEND 

.COM 


SET 

.COM 

SET 

.COM 

SET 

.COM 


SHOW 

.COM 

SHOW 

.COM 

SHOW 

.COM 


TYPE 

.COM 

TYPE 

.COM 

TYPE 

.COM 


USER 

.COM 

USER 

.COM 

USER 

.COM 


VERIFY 

.COM 

VERIFY 

.COM 

VERIFY 

.COM 
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CODING CONVENTIONS 


Assembler Notes 


This section is devoted to in-depth discus- 
sion of TurboDOS internal coding conventions, 
aimed at the systems programmer writing hard- 
ware-dependent drivers or resident processes. 


Drivers and resident processes for Z80 Turbo- 
DOS must be written using a Z80 assembler 
capable of producing relocatable modules with 
symbolic linkage information in the industry- 
standard Microsoft relocatable module format. 
Both Microsoft's M80 and Digital Research's 
RMAC assemblers produce object code in this 
format, and are fine choices for use with 
TurboDOS. 

Another excellent relocatable Z80 assembler 
is PASM from Phoenix Software Associates, 
However, PASM produces object modules in a 
non-standard format. 

To make it possible for PASM to be used with 
TurboDOS, a conversion utility (RELVCT.COM) 
for converting PASM object modules to stan- 
dard Microsoft format is furnished with 
TurboDOS. The command: 


I RELCVT filename 


I 

I 

I 


converts the specified PASM-format .REL file 
into Microsoft .REL format. During conver- 
sion, the character , is converted to ?, and 
the character % is converted to @ wherever 
these characters appear in symbol names. 
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CODING CONVENTIONS 

Assembler Notes 
(Continued) 


Programming examples and driver listings in 
this document are coded for PASM. If you are 
used to another assembler, please take note 
of certain syntax features of PASM which may 
be different in other assemblers. 

Names followed by # are external references 
to public names defined in other modules. 
Labels followed :: are public names available 
for reference in other modules. Some assem- 
blers require such names to be declared using 
an EXTERN or PUBLIC directive. 

Program, data, and common segments are intro- 
duced with a .LOC directive. Other assem- 
blers use different directives such as CSEG, 
DSEG, COMMON, etc. to accomplish the same 
thing. 

Finally, the symbol . represents the current 
location counter value. Some assemblers use 
$ or * instead. 


To allow various TurboDOS modules to be in- 
cluded or omitted at will, the GEN command 
automatically resolves all undefined external 
references to the default symbol public ?UND? 
{.UND. using PASM). The common subroutine 
module COMSUB contains the following subrou- 
tine : 


.UND.:: NOP 


;two bytes of zero 

NOP 


.it n n if 

r 

XRA 

A 

?clear A to zero 

RET 


;done 


Thus, it is always safe to load or call an 
external name, whether or not it is present 
at GEN time. It is bad form to store into an 
undefined external name, however l 
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Memory Allocation 


The TurboDOS resident occupies the topmost 
portion of memory in a Z80 system. A common 
memory management module MEMMGR provides 
dynamic allocation and deallocation of memory 
space required for disk and message buffers, 
print queues, file and record locks, do-file 
nesting, and so forth. Memory segments are 
allocated downward from the base of the 
TurboDOS resident, reducing the space 
available for TPA, Deallocated segments are 
concatenated with any neighbors and threaded 
on a free-memory list. A best-fit algorithm 
is used to reduce memory fragmentation. 

Allocation and deallocation requests are 
coded in this manners 


;code 

to allocate a memory segment 


LXI 

H,36 

;HL~segment size 


CALL 

ALLOC# 

/■allocate segment 


ORA 

A 

;alloc successful? 


JNZ 

ERROR 

;NZ -> not enuf mem 


PUSH 

H 

;HL~segment address 

;code 

to deallocate a 

memory segment 


POP 

H 

;HL~segraent address 


CALL 

DEALOC# 

; deallocate segment 


ALLOC# prefixes each allocated segment with a 
word containing the segment length, so that 
DEALOC# can tell how much memory is to be 
deallocated. ALLOC# does not zero the newly- 
allocated segment. 
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List Processing TurboDOS maintains its dynamic structures as 

threaded lists with bidirectional linkages. 
This technique permits a node to be added or 
deleted anywhere in a list without searching. 
The list head and each list node have a two- 
word linkage (forward and backward pointers) . 

List manipulation is coded in this manner: 


.LOG .DATA.# ;data segment 
;list head (linkage initialized empty) 
LSTHED : .WORD LSTHED ;forward pointer 
.WORD LSTHED ;backward pointer 

;list node (linkage not initialized) 
LSTNOD: .WORD 0 ; forward pointer 

.WORD 0 ;backward pointer 

.BYTE [128] 0 ?contents of node 

.LOC .PROG.# ;program segment 
;code to add node to end of list 

LXI H f LSTHED ;HL=head address 
LXI D, LSTNOD ;DE=node address 
CALL LNKEND# ylink to list end 

;code to unlink node from list 

LXI H r LSTNOD yHL-node address 
CALL UNLINK# ; unlink node 

ycode to add node to beginning of list 
LXI H, LSTHED ?HL=head address 
LXI D, LSTNOD ?DE=node address 
CALL LNKBEG# ylink to list beg. 
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Task Dispatching 


TurboDOS incorporates a flexible, efficient 
mechanism for dispatching the Z80 processor 
among various competing processes. In coding 
drivers for TurboDOS, you must take extreme 
care to use the dispatcher correctly in order 
to attain maximum system performance. 

The dispatcher allows one process to wait for 
some event (for example, da ta-available or 
seek-complete) while allowing other processes 
to use the processor. For each such event, 
you must define a three-word structure called 
a "semaphore”. 

A semaphore consists of a count-word followed 
by a two-word list head. The count-word is 
used by the dispatcher to keep track of the 
status of the event, while the list head 
anchors a threaded list of processes waiting 
for the event to occur. 

Two primitive operations operate on a sema- 
phore: waiting for the event to occur 
(WAIT#), and signalling that the event has 
occurred (SIGNAL#). They are coded in this 
following manner: 


?this semaphore represents some event 
EVENT: .WORD 0 ; semaphore count 

.WORD EVENT+2 /semaphore f-ptr 

.WORD EVENT+2 /semaphore b-ptr 


/wait for the event to occur 

LXI H, EVENT /HL=semaphor e addr 
CALL WAIT# /wait for event 


/signal that event has occurred 

LXI H, EVENT /HL^ semaphore addr 
CALL SIGNAL# /signal event 


I 
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CODING CONVENTIONS 

Task Dispatching 
(Continued) 


Whenever a process waits on a semaphore, 
WAIT# decrements the semaphore's count-word. 
Thus, a negative count -N signifies that 
there are N processes waiting for the event 
to occur. Whenever an event is signalled, 
SIGNAL# increments the semaphore count-word 
and awakens the process that has been waiting 
longest. 

If an event is signalled but no process is 
waiting for it, then SIGNAL# increments the 
count-word to a positive value. Thus, a 
positive count N signifies that there have 
been N occurrences of the event for which no 
process was waiting. In this case, the next 
N calls to WAIT# on that semaphore will 
return immediately without waiting. 

Sometimes it is necessary for a process to 
wait for a specific time interval (for exam- 
ple, a motor-start delay or carriage-return 
delay) rather than for a specific event. 
TurboDOS provides a delay facility (DELAY#) 
that permits other processes to use the Z80 
while one process is waiting for such a timed 
delay. Delay intervals are specified as some 
number of "ticks". A tick is an implementa- 
tion-defined interval, usually 1/50 or 1/60 
of a second. Delays are coded thus: 


j ? delay for one- tenth of a second i 

| LXI H, 6 ;HL-delay in ticks | 

j CALL DELAY# ? delay process I 

I I 

Accuracy of delays is usually plus-or-minus 
one tick. A delay of zero ticks may be 
specified to relinquish the processor to 
other processes on a "courtesy" basis. 

All driver delays should be accomplished via 
WAIT# or DELAY#, never by spinning in a loop. 
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CODING CONVENTIONS 
Interrupt Service 


Dispatching is especially efficient when used 
with interrupt-driven devices* Usually, the 
interrupt service routine just calls SIGNAL# 
to signal the interrupt-associated event* 

Most interrupt service routines should exit 
via the usual EI/RETI sequence* However, 
some periodic interrupt (usually a 50 or 60 
hertz clock interrupt) should have an inter- 
rupt service routine that exits by jumping to 
the dispatcher entrypoint ISRXIT# (without 
enabling interrupts) to provide periodic 
time-slicing of processes. To avoid exces- 
sive dispatcher overhead, don't use ISRXIT# 
more than about 60 times per second. 

It is good programming practice for interrupt 
service routines to set up an auxilliary 
stack, in order to avoid the possibility of 
overflowing the stack area of some transient 
program. TurboDOS provides a standard inter- 
rupt stack area INTSTK# and stack pointer 
save location INTSP#. A simple interrupt 
service routine might be coded like this: 


I DEVISR : 

SSPD 

INTSP# 

‘save user SP 



LXI 

SP, INTSTK i 

\ ;SP=aux stack 



PUSH 

PSW 

save registers 



PUSH 

B 

n n 



PUSH 

D 

n n 



PUSH 

H 

ti if 



IN 

PORT 

reset interrupt 



LXI 

H, EVENT 

HL=semaphore addr 



CALL 

SIGNAL# 

signal event 



POP 

H 

restore registers 



POP 

D 

n n 



POP 

B 

n n 



POP 

PSW 

n n 



LSPD 

El 

RETI 

INTSP# 

restore user SP 
enable interrupts 
return from int. 
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CODING CONVENTIONS 
Poll Routines 


Devices incapable of interrupting the Z80 
have to be polled by the driver* The dis- 
patcher maintains a threaded list of poll 
routines, and executes them every dispatch. 
The function of each poll routine is to check 
the status of its device, and to signal the 
occurrence of some event (for example, data- 
available) when it occurs. The routine 
LNKPOL # links a poll routine onto the poll 
list, and UNLINK# removes it. 

A poll routine must be coded so that it will 
not signal the occurrence of a particular 
event more than once. The best way to assure 
this is for the poll routine to unlink itself 
from the poll list as soon as it has signal- 
led the event. An example: 


EVENT: 

WORD 

0 

; semaphore 


WORD 

EVENT+2 



WORD 

EVENT+2 


;driver 

waits 

for event 



LXI 

D, POLNOD 

;DE=poll node addr 


CALL 

LNKPOL# 

;activate poll rtn 


CALL 

POLRTN 

;optional pretest 


LXI 

H , EVENT 

;HL=semaphore addr 


CALL 

WAIT# 

;wait for event 

;poll routine 

signals event when detected 

POLNOD : 

.WORD 

0 

;poll rtn linkage 


.WORD 

0 

. n it it 

t 

POLRTN : 

IN 

PORT 

;get device status 


AN I 

MASK 

?did event occur? 


RZ 


;if not, exit 


LXI 

H, EVENT 

;HL=semaphore addr 


CALL 

SIGNAL# 

; signal event 


LXI 

H, POLNOD 

?HL=linkage addr 


CALL 

UNLINK# 

;unlink poll rtn 


RET 


?all done 
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CODING CONVENTIONS 
Mutual Exclusion 


TurboDOS is fully re-entrant at the process 
and kernel levels. However, most driver 
modules are not coded re-entrantly (since 
most peripheral devices can only do one thing 
at a time). Consequently, most drivers must 
make use of a mutual-exclusion interlock to 
prevent TurboDOS from invoking them re-ent- 
rantly . 

This is very easy to accomplish using the 
basic semaphore mechanism of the dispatcher. 
It is only necessary to define a semaphore 
with its count-word initialized to 1 (instead 
of 0). Mutual exclusion may then be accom- 
plished by calling WAIT# upon entry and 
SIGNAL# upon exit. An example: 


I 

i 

I 


/mutual-exclusion semaphore 
MXSPH : .WORD 1 ? count-word=l l 

.WORD MXSPH+2 
.WORD MXSPH+2 

DRIVER: LXI H, MXSPH ;HL=semaphor e addr 
CALL WAIT# ;wait if in-use 


LXI H, MXSPH 
CALL SIGNAL# 
RET 


;HL=semaphore addr 
/unlock mut-excl 
/done 


4-9 




TurboDOS 1.3 Z80 
Implementor's Guide 


Sample Driver 
Using Interrupts 


CODING CONVENTIONS 

Sample Driver 
Using Interrupts 


Here is a simple device driver for an inter— 


rupt-driven serial input device. It illus 
trates coding techniques discussed so far: 


i 

i 

MXSPH : 

.WORD 

i 

►MX semaphore 

i 

i 

i 


.WORD 

MXSPH+2 


i 

! 


.WORD 

MXSPH+2 


i 

1 

RDASPH : 

.WORD 

0 

RDA semaphore 

i 

1 


.WORD 

RDASPH+2 


i 

1 


.WORD 

RDASPH+2 


i 

1 

CHRSAV : 

.BYTE 

0 

saved input char 

i 

1 

;device 

driver main code 

i 

1 

INPDRV : 

:LXI 

H r MXSPH 

HL=MX semaph addr 

i 

1 


CALL 

WAIT# 

lock MX 

i 

1 


El 


need ints enabled 

i 

1 


LXI 

H, RDASPH 

HL=semaphore addr 

i 

1 


CALL 

WAIT# 

wait data avail 

i 

1 


LDA 

CHRSAV 

get input char 

i 

I 


PUSH 

PSW 

save on stack 

i 

1 


LXI 

H, MXSPH 

HL=MX semaph addr 

i 

1 


CALL 

SIGNAL# 

unlock MX 

i 

1 


POP 

PSW 

return char in A 

i 

I 


RET 


done 

i 

1 

;interrupt service routine 

i 

1 

INPISR : 

:SS PD 

INTSP# 

►save user's SP 

i 

1 


LXI 

SP, INTSTK# ;SP=aux stack 

i 

1 


PUSH 

PSW 

save registers 

i 

1 


PUSH 

B 

it n 

i 

1 


PUSH 

D 

tt n 

i 

1 


PUSH 

H 

n n 

i 

1 


IN 

PORT 

get input char 

i 

1 


STA 

CHRSAV 

save for driver 

i 

1 


LXI 

H, RDASPH 

HL-semaphore addr 

i 

1 


CALL 

SIGNAL# 

signal data avail 

i 

1 


POP 

H 

restore registers 

i 

1 


POP 

D 

n n 

i 

1 


POP 

B 

n n 

i 

1 


POP 

PSW 

it n 

i 

1 


LSPD 

INTSP# 

restore user SP 

i 

1 


El 


enable interrupts 

i 

1 


RETI 


return from int. 

i 

i 
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CODING CONVENTIONS 

Sample Driver 
Using Polling 


Here is a simple device driver for non-inter- 
rupting serial input device. It illustrates 
how polling is used: 



MXSPH: 

.WORD 

1 

; MX semaphore 




.WORD 

MXSPH+2 





.WORD 

MXSPH+2 




RDASPH : 

• WORD 

0 

?RDA semaphore 




.WORD 

RDASPH+2 





.WORD 

RDASPH+2 




CHRSAV : 

.BYTE 

0 

/saved input char 



/device 

driver main code 



INPDRV : 

:LXI 

H, MXSPH 

/HL=MX semaph addr 




CALL 

WAIT# 

;lock MX 




LXI 

D, POLNOD 

/ DE=poll rtn node 




CALL 

LNKPOL# 

/activate poll rtn 




CALL 

POLRTN 

/optional pretest 




LXI 

H r RDASPH 

/HL=semaphore addr 




CALL 

WAIT# 

/wait data avail 




LDA 

CHRSAV 

/get input char 




PUSH 

PSW 

/save on stack 




LXI 

H, MXSPH 

/ HL=MX semaph addr 




CALL 

SIGNAL# 

/unlock MX 




POP 

PSW 

/return char in A 




RET 


/done 



? device 

poll routine with linkage 



POLNOD: 

.WORD 

0 

/poll rtn linkage 




.WORD 

0 




POLRTN : 

IN 

STATUS 

/get device status 




ANI 

MASK 

/data available? 




RZ 


/if not, exit 




IN 

DATA 

/get input char 




STA 

CHRSAV 

/save for driver 




LXI 

H, RDASPH 

/HL=semaphore addr 




CALL 

SIGNAL# 

/signal data avail 




LXI 

H, POLNOD 

/HL-linkage addr 




CALL 

UNLINK# 

/unlink poll rtn 




RET 


/done 



4-11 



TurboDOS 1.3 Z80 
Implementor's Guide 


CODING CONVENTIONS 


Special Segments 


Special Segments In addition to the usual code and data seg- 
ments, GEN command supports three special 
location counters (common blocks): 


1 J__PA£1L_L 

i 

Description 

~ i 

1 ?INIT? 

. INIT. # 

Initialization code 

i 

i 

I ?PAGE? 

.PAGE. # 

Page-boundary aligned 

i 

1 ?BANK? 
1 

.BANK. # 

Banked-memory common 

i 

i 






?INIT? Segment In coding driver modules, you will often find 

a considerable amount of initialization code 
that is executed only once at cold-start and 
never needed again. By assembling such code 
under ?INIT? (.INIT.# using PASM) , it will be 
loaded and executed in lower memory (TPA) , 
and will not occupy space in the resident 
operating system. 


?PAGE? Segment Sometimes you may need to force a segment of 

code or data to begin on a 256-byte page 
boundary. Examples are the simulated CP/ M 
BIOS branch table, and interrupt vectors for 
Z80 interrupt mode 2. By assembling under 
?PAGE? (.PAGE.# using PASM), the segment is 
guaranteed to be page-aligned. 


7BANK? Segment In banked-memory implementations, you need to 

be able to place certain code and data in the 
topmost part of memory which is common to 
both banks (not switched). Anything assem- 
bled under ?BANK? (.BANK.# using PASM) will 
be assigned to this common region (as speci- 
fied by the ;Kxxxx option on the GEN com- 
mand) . 
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CODING CONVENTIONS 

Inter-Process 

Messages 


To pass messages from one process to another, 
a five-word structure called a "message node" 
is used. A message node consists of a three- 
word semaphore followed by a two-word message 
list head. Routines are provided for sending 
messages to a message node (SNDMSG#), and 
receiving messages from a message node 
(RCVMSG # ) • Typically, the sending process 
allocates a memory segment in which to build 
the message, and the receiving process deal- 
locates the segment after reading the mes- 
sage. The first two words of each message 
must be reserved for a list-processing link- 
age. Coding is done in this manner: 


/message node 



MSGNOD: .WORD 

0 

/semaphore part 


.WORD 

MSGNOD+2 

, n n 

f 


.WORD 

MSGNOD+2 

• n ” 
t 


.WORD 

MSGNOD+6 

/message list head 


.WORD 

MSGNOD+6 

.« it » 

t 


;one process 

allocates/builds/sends msg 


LXI 

H, 12+4 

/HL^message size+4 


CALL 

ALLOC# 

/allocate segment 


PUSH 

H 

/save segment addr 


; 


/build msg in seg 


POP 

D 

/DE=message addr 


LXI 

H, MSGNOD 

/HL=msg node addr 


CALL 

SNDMSG# 

/send message 


/other process reads/deallocates message 


LXI 

H, MSGNOD 

/HL=msg node addr 


CALL 

RCVMSG# 

/receive message 


PUSH 

H 

/save message addr 


: 


/process message 


POP 

H 

/HL=segment addr 


CALL 

DEALOC# 

/deallocate seg 
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CODING CONVENTIONS 
Console Routines 


TurboDOS includes several handy console I/O 
subroutines which may be called from within 
driver modules as illustrated: 


;raw console I/O routines 


CALL 

CONST# 

;get status in A 

ORA 

A 

; input char avail? 

RZ 


?if not, exit 

CALL 

CON IN# 

;get input in A 

CALL 

UPRCAS# 

;make upper-case 

MOV 

C,A 

;C=character 

CALL 

CONOUT# 

;output chr from C 

! output routines 

lar of 

message has sign-bit set 

CALL 

DMS# 

;output following 

.ASCIS "This is 

a message" 

LXI 

H , MSGADR 

;HL=message addr 

CALL 

DMSHL# 

;output msg @ HL 

■to-decimal output routine 

LXI 

H, 31416 

;HL=word value 

CALL 

DECOUT# 

ydisplays decimal 


You may add your own custom sign-on message 
to TurboDOS. Your message will be displayed 
at cold-start immediately following the nor- 
mal TurboDOS sign-on and copyright notice. 

Your sign-on message must be coded as an 
ASCII character string terminated with a the 
usual $ delimiter, and labelled with the 
public entry symbol USRSOM. An example: 


USRSOM: : .ASCII [ ODH] [OAH] 

.ASCII "Implementation by " 
.ASCII "Trigon Computer Corp. " 
.ASCII 


4-14 





TurboDOS 1.3 Z80 
Implementor's Guide 


Resident Process 


CODING CONVENTIONS 
Resident Process 


You can code a resident process that runs in 
the background concurrent with other system 
activities, and link it into TurboDOS, The 
cr ea te-pr ocess subroutine CRPROC# may be 
called to create such a process at cold-start 
as shown: 


,LOC 

. INIT. # 

;init code 

HDWNIT: :LXI 

H,64 

;HL-workspace size 

CALL 

ALLOC# 

;alloc workspace 



;HL=*workspace addr 

LXI 

D, MYPROC 

;DE=entrypoint add 

CALL 

CRPROC# 

jcreate process 

• LOC 

.PROG.# 

;code segment 

MYPROC : INR 

COUNT (Y) 

;increment counter 

LXI 

D, 60*60 

; 1 minute in ticks 

[ MV I 

C,2 

;T-function 2 

CALL 

OTNTRY# 

; delay 1 minute 

JMP 

MYPROC 

;loop forever 


CRPROC# automatically allocates a TurboDOS 
process area (address appears in register X) 
and a stack area (address appears in SP). If 
the process requires a re-entrant workspace, 
it should be allocated with ALLOC# and passed 
to CRPROC# in HL (as shown above), and will 
appear to the new process in register Y, 

The resident process must make all operating 
system requests by calling OCNTRY# or OTNTRY# 
with a C-function or T-function number 
register C. It must not call location 0005H 
or 0 0 50 H in the base page, nor make direct 
calls on kernel routines such as WAIT#, 
SIGNAL#, DELAY#, SNDMSG #, RCVMSG#, ALLOC#, 
and DEALOC#. 
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CODING CONVENTIONS 

Resident Process 
(Continued) 


A resident process is not attached to a con- 
sole, so any console I/O requests will be 
ignored. 

You can do file processing within a resident 
process, using the normal C-functions open, 
close, read, write, and so forth, called via 
OCNTRY#. First, however, you must remember 
to warm-start with C-function 0 (OCNTRY#) , 
and then log-on with T-f unction 14 (OTNTRY#) . 

A resident process must always be coded to 
preserve the contents of index register X, 
which Turbodos relies upon as a pointer to 
its process area. The process may use all 
other registers as desired. 


The User-Defined Function (T-function 41) 
provides a means of adding your own special 
functions to the normal TurboDOS repertoire 
of C-functions and T-functions. To do this, 
you simply create a function processor sub- 
routine with the public entrypoint symbol 
USRFCN. 

Whenever a program invokes T-function 41, 
TurboDOS transfers control to your USRFCN 
routine. On entry, register BC contains the 
address of the 128-byte record area passed 
from the caller's current DMA address, and 
registers DE and HL contain whatever values 
the caller loaded into them. Your USRFCN 
routine may return data to the caller in the 
128-byte record area (address in BC at entry) 
and in any of the registers A-B-C-D-E-H-L. 

Architecturally, your USRFCN routine is in- 
side the TurboDOS kernel. Consequently, it 
may call kernel subroutines directly. Any 
calls to C-functions and T-functions must 
therefore be made by means of two special 
recursive entrypoints: XCNTRY# and XTNTRY#. 
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DRIVER INTERFACE This section explains how to code hardware- 

dependent device driver modules, and presents 
formal interface specifications for each 
category of driver required by TurboDOS. 


General Notes Drivers modules are coded with standard pub- 

lic entrypoint names, and linked to TurboDOS 
using the GEN command. You may package your 
drivers into as many or few separate modules 
as you like. In general, it is easier to 
reconfigure TurboDOS for a variety of devices 
if the driver for each device is packaged as 
a separate module. 

TurboDOS is designed to accomodate multiple 
disk, console, printer, and network drivers. 
For disk drivers, for instance, the DSKAST 
is normally set up to refer to disk driver 
entrypoints DSKDRA# , DSKDRB# , DSKDRC#, and so 
forth. Each disk driver should be coded with 
the public entrypoint DSKDR @ ( DSKDR% using 
PASM) . The GEN command automatically maps 
successive definitions of such names by 
replacing the trailing @ by A, B, C, etc. 
The same technique may be used for console, 
printer, and network driver entrypoints. 

You must code driver routines to preserve the 
stack and index registers X and Y, but you 
may use other registers as desired. 
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DRIVER INTERFACE 
Initialization 


Hardware initialization and interrupt vector 
set-up should be performed in an initializa- 
tion routine labelled with the public entry 
symbol HDWNIT::. TurboDOS calls this routine 
during cold-start with interrupts disabled. 

Your HDWNIT: : routine must not enable inter- 
rupts or make calls to WAIT# or DELAY#. In 
most cases, HDWNIT: : will contain a series of 
calls to individual driver initialization 
subroutines contained in other modules. 

One-time initialization code that is not 
needed again should be assembled under the 
special location counter ?INIT?, so that it 
doesn't take up space in the resident opera- 
ting system. 
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DRIVER INTERFACE 
Console Driver 


A console driver should be labelled with the 
public entry symbol CONDR@ {CONDR%:: using 
PASM). A console number (from CONAST) is 
passed in register B. The driver must per- 
form a console I/O operation according to the 
operation code passed in register E: 


E-reg J Function 

0 Return status in A, char in C 

1 Return input character in A 

2 Output character passed in C 

8 Enter error-message mode 

9 Exit error-message mode 

10 Conditional output char in C 


If E=0, the driver determines if a console 
input character is available. If no charac- 
ter is available, the driver returns A-0. If 
an input character is available, the driver 
returns A=-l and the input character in C, 
but must not "consume" the character . Turbo- 
DOS depends upon this look-ahead capability 
to detect attention requests. The driver 
must not dispatch (via WAIT# or DELAY#) when 
processing an E=0 call. 

If E«1 , the driver obtains an input character 
(waiting if necessary) and returns it in A. 

If E=2, the driver displays the output char- 
acter passed in C (waiting if necessary). 

If E=8, the driver prepares to display a 
TurboDOS error message; if E=9, it reverts to 
normal. TurboDOS always precedes each error 
message with an E=8 call and follows it with 
an E=9 call. This gives the driver an oppor- 
tunity to take special action (25th line, 
reverse video, etc.) for error messages. For 
simple consoles, the driver should output a 
CR-LF in response to E=8 and E=9 calls. 


5-3 




Turbo DOS 1.3 Z80 
Implementor's Guide 


Console Driver 
(Continued) 


DRIVER INTERFACE 

Console Driver 
(Continued) 


If E=10, the driver determines whether or not 
it can accept a console output character 
without dispatching (via WAIT# or DELAY#). 
If so, it outputs the character passed in C, 
and returns A=-l to indicate that the charac- 
ter was accepted. However, if the driver 
cannot accept a console output character 
without dispatching, it returns A=0 to indi- 
cate that the character was not accepted; 
TurboDOS will then make an E = 2 call to output 
the same character. This special conditional 
output call is used by TurboDOS to optimize 
console output speed by avoiding certain 
dispatch-related overhead whenever possible. 

You should make a special effort to code the 
console driver to execute the minimum number 
of instructions possible, especially func- 
tions 0, 2, and 10. Excessive use of subrou- 
tine calls, stack operations, and other time- 
consuming coding techniques can make the 
difference between running the console device 
at full rated speed or something less. Study 
the sample driver listings in the appendix 
with this in mind. 
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DRIVER INTERFACE 
Printer Driver 


A printer driver should be labelled with the 
public entry symbol LSTDR @ (LSTDR% : : using 
PASM). A printer number (from PTRAST) is 
passed in register B. The driver must per- 
form a printer output operation according to 
the operation code passed in register E: 

I fi-reg I Eanciasp I 

I I 

I 2 Print character passed in C I 

i 7 Perform end-of-print- job action | 


If E=2 , the driver prints the output charac- 
ter passed in C (waiting if necessary). 

If E=7 , the driver takes any appropriate end- 
of-print-job action. This is quite hardware- 
dependent, and may include slewing to top-of- 
form, homing the print head, dropping the 
ribbon, and so forth. 
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Disk Driver 


A disk driver should be labelled with the 
public entry symbol DSKDR@ (DSKDR%:: using 
PASM). The driver performs the physical disk 
operation specified by the Physical Disk 
Request (PDR) packet whose address is passed 
by TurboDOS in index register X. The struc- 
ture of the PDR packet is: 


Offset 1 

_ Contents 

;physical disk request 

(PDR) packet 

0 (X) 

•BYTE OPCODE 

;operation code 

1(X) 

•BYTE DRIVE 

;drive (base 0) 

2 (X) 

•WORD TRACK 

;track (base 0) 

4 (X) 

.WORD SECTOR 

;sector (base 0) 

6 (X) 

.WORD SECCNT 

;#sectors to rd/wr 

8(X) 

•WORD BYTCNT 

; tbytes to rd/wr 

10 (X) 

•WORD DMAADR 

;DMA addr to rd/wr 

12 (X) 

• WORD DS T ADR 

; DST address 

; copy of 

disk specification table (DST) 

14 (X) 

•BYTE BLKSIZ 

;block size (3-7) 

15 (X) 

•WORD NMBLKS 

;#blocks on disk 

17 (X) 

•BYTE NMBDIR 

;#directory blocks 

18 (X) 

•BYTE SECSIZ 

;sector size (0-7) 

19(X) 

•WORD SECTRK 

;sectors per track 

21 (X) 

•WORD TRKDSK 

;tracks on disk 

1 23 (X) 

•WORD RESTRK 

;reserved tracks 


The operation to be performed by the driver 
is specified in the first byte of the PDR 
packet (OPCODE) as follows: 


OPCODE 1 EUBfijOflli 

0 Read sectors from disk 

1 Write sectors to disk 

2 Determine disk type, return DST 

3 Determine if drive is ready 

4 Format track on disk 
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If OPCODE=0 , the driver reads SECCNT physical 
sectors (or equivalently, BYTCNT bytes) into 
DMAADR, starting at TRACK and SECTOR on 
DRIVE. The driver returns A=0 if the opera- 
tion is successful, or A=-l if an unrecover- 
able error occurs. TurboDOS may request 
multiple consecutive sectors to be read, but 
will never request an operation that extends 
past the end of the track. 

If OPCODE=1, the driver writes SECCNT physi- 
cal sectors (or BYTCNT bytes) from DMAADR, 
starting at TRACK and SECTOR on DRIVE. The 
driver returns A=0 if the operation is suc- 
cessful, or A=-l if an unrecoverable error 
occurs. TurboDOS may request multiple con- 
secutive sectors to be written, but will 
never request an operation that extends past 
the end of the track. 

If 0PC0DE=2 , the driver must determine the 
type of disk mounted in DRIVE, and must 
return, in the DSTADR field of the PDR 
packet, the address of an 11-byte disk speci- 
fication table (DST) structured as follows: 


- Offset 

i - 

..Description 

0 

block 

size (3=1K,4=2K, . . . ,7=16K) 

1-2 

total 

number of blocks on disk 

3 

number 

of directory blocks 

4 

sector 

size (0=128, . . . ,7=16K) 

5-6 

number 

of sectors per track 

7-8 

number 

of tracks on the disk 

9-10 

number 

of reserved (boot) tracks 


The first byte of the DST (BLKSIZ) specifies 
the allocation block size in bits 2-0. In 
addition, bit 7 is set if the disk is fixed 
(non-removable), and bit 6 is set if file 
extents are limited to 16K (EXM=0) . 
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The driver returns A=-l if the operation is 
successful, or A=Q if the drive is not ready 
or the disk type is unrecognizable. On 
successful return, TurboDOS moves a copy of 
the DST into 14(X) through 24(X), where it is 
available for subsequent operations. 

If 0PC0DE=3, the driver determines whether 
DRIVE is ready, and returns A=-l if it is 
ready or A=0 if not. 

If 0PC0DE=4, the driver formats (initializes) 
TRACK on DRIVE, using hardware-dependent 
formatting information at DMAADR (put there 
by the FORMAT command). The driver returns 
A=0 if successful, or A=-l if an unrecover- 
able error occurs. 
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Bank-Select Driver Banked-memory systems must include a bank- 

select driver labelled with the public entry 
symbol SELBNK::. The function of this rou- 
tine is simply to select the memory bank (0 
or 1) passed in register A. The routine 
should be coded under the special location 
counter ?BANK? to ensure it is situated in 
unswitched common memory. In addition, the 
SELBNK:: routine must preserve all registers 
other than A. 

All interrupt-driven drivers in a banked- 
memory system must be designed to service 
interrupts properly regardless of which bank 
is active when an interrupt occurs. Drivers 
for DMA disk controllers must ensure that DMA 
operations transfer into or out of bank 0 
only. Study the sample drivers in the appen- 
dix for suggested techniques. 
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A network circuit driver should be labelled 
with the public entry symbol CKTDR0 (CKTDR%:s 
using PASM). A message buffer address is 
passed in register DE. The driver must 
either send or receive a network message, 
according to the operation code passed in 
register C: 


C-reg. _1. 

0 Receive message into buffer at DE 

1 Send message from buffer at DE 


If OO, the driver receives a network message 
into the message buffer whose address is 
passed in DE (waiting if necessary). If a 
message is received successfully, the driver 
returns A=0. If an unrecoverable malfunction 
of any remote processor is detected, the 
driver returns A=-l with the network address 
of the crashed processor in DE. 

If C=1 , the driver sends a network message 
from the message buffer whose address is 
passed in DE. If the message is sent suc- 
cessfully, the driver returns A=0, If the 
message could not be sent because of an unre- 
coverable malfunction of the destination 
processor, the driver returns A=-l with the 
network address of the crashed processor in 
DE. 

The structure of a network message buffer is 
shown on the facing page. The first four 
bytes of the buffer are reserved for a 
linkage used by TurboDOS, and should be 
ignored by the driver. The 11-byte message 
header and v a r i a bl e- 1 eng th message body 
should be sent or received over the circuit. 
The driver should only need to look at the 
first two header fields (MSGLEN and MSGDID) . 


5-10 


TurboDOS 1.3 280 
Implementor's Guide 


Network Driver 
(Continued) 


DRIVER INTERFACE 

Network Driver 
(Continued) 


message buffer format 

.WORD ? ;linkage (ignored) 

.WORD ? ; " 

11-byte message header 


.BYTE MSGLEN 
.WORD MSGDID 
.BYTE MSGPID 
.WORD MSGS ID 
.WORD MSGOID 
.BYTE MSGOPR 
.BYTE MSGLVL 
.BYTE MSGFCD 
variable-length body 
. BLKB 7 
. BLKB 38 
.BLKB 128 


;msg length 
destination addr 
jprocess id 
j source addr 
;originator addr 
;orig'r process id 
; forwarding level 
;rasg format code 

jregisters ACBEDLH 
; optional FCB data 
;optional record 


The length field MSGLEN represents the number 
of bytes in the message, including the header 
and body (but excluding the linkage). On a 
receive request (C=0), TurboDOS presets 
MSGLEN to the maximum allowable message 
length, and expects MSGLEN to contain the 
actual message length on return. On a send 
request (C=l), TurboDOS presets MSGLEN to the 
actual length of the message to be sent. 

In a server/user network, it is often desir- 
able for the circuit driver in the server to 
periodically "poll" the user processors on 
the circuit to detect any user malfunctions 
quickly and to effect recovery. If the 
driver reports that a user has crashed (by 
returning A=-l and DE=network-address) , then 
the circuit driver must not accept any fur- 
ther messages from that user until TurboDOS 
has completed its recovery process. 
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TurboDOS signals the driver that such recov- 
ery is complete by sending a dummy message 
destined for the user in question with a 
length of zero. The driver should not actu- 
ally send such a message to the user, but 
could initiate whatever action is appropriate 
to reset the user and download a new copy of 
the user operating system. 

A user must request an operating system 
download by sending a special download re- 
quest message to the server (usually done by 
a bootstrap routine) . The download request 
message consists of a standard 11-byte header 
(with MSGPID, MSGOID and MSGFCD zeroed) fol- 
lowed by a 1-byte body containing a "download 
suffix" character. The server processor 
addressed by MSGDID will return a reply mes- 
sage whose 128-byte body is the first record 
of the download file OSUSERx.SYS (where "x" 
is the specified download suffix) . 

The user continues to send download request 
messages and to receive successive download 
records until it receives a short reply mes- 
sage (1-byte body) signifying end-of-file. 
The first word of the downloaded file speci- 
fies the base address to which the downloaded 
system should be moved, and the second word 
specifies the total byte-length of the sys- 
tem, The single byte passed as the body of 
the final short message identifies the system 
disk, and should be passed to the system in 
register A. 

The entire failure detection, failure recov- 
ery, and user downloading procedure is very 
hardware-dependent . 
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The comm driver supports the TurboDOS commu- 
nications extensions (T-f unctions 34-40), and 
may be omitted if these functions are not 
used. The driver should be labelled with the 
public entry symbol COMDRV::. A comm channel 
number is passed in register B. The driver 
must perform an I/O operation according to 
the operation code passed in register E: 


E- .ie g ,1 


Fu nction- 


0 Return input status in A 

1 Return input character in A 

2 Output character passed in C 

3 Set channel baud rate from C 

4 Return channel baud rate in A 

5 Set modem controls from C 

6 Return modem status in A 


If E=0, the driver determines if an input 
character is available. If one is available, 
the driver returns A=-l, otherwise A=0. 

If E=l, the driver obtains an input character 
(waiting if necessary) and returns it in A, 

If E=2, the driver outputs the character 
passed in C. 

If E=3, the driver sets the channel baud rate 
according to the baud-rate code passed in C. 
If E=4, the driver returns the channel baud- 
rate code in A. See T-functions 37 and 38 
in the Z 8P Progra mm er's Guide for baud-rate 
code definitions. 

If E=5, the driver sets the modem controls 
according to the bit-vector passed in C. If 
E=6, the driver returns the modem status 
vector in A. See T-functions 39 and 40 in 
the Z 80 Progra mm er's Guide for bit-vector 
definitions. 


5-13 



TurboDOS 1.3 
Implementor 1 


Clock Driver 


Z80 DRIVER INTERFACE 

' Guide 

Clock Driver 


The real-time clock driver does not take the 
form of a subroutine called by TurboDOS, as 
do the other drivers described in this sec- 
tion. Rather, the clock driver generally 
consists of an interrupt service routine 
which responds to interrupts from a periodic 
interrupt source (preferably 50 to 60 times a 
second). The interrupt service routine 
should call DLYTIC# once per system tick (to 
synchronize DELAY# requests). It should also 
call RTCSEC# once per second (that is, every 
50 to 60 ticks) to update the system time and 
date. Finally, it should exit by jumping to 
ISRXIT# to provide a periodic dispatcher 
time-slice. Excluding initialization code, a 
typical clock driver might be coded thus: 



RTCCNT: 

.BYTE 

60 

divide-by-60 cntr 



RTCISR : 

SSPD 

INTSP# 

•save user’s SP 




LXI 

SP, INTSTK# ;SP=aux stack 




PUSH 

PSW 

save registers 




PUSH 

B 

w n 




PUSH 

D 

n n 




PUSH 

H 

i? it 




IN 

PORT 

reset interrupt 




CALL 

DLYTIC# 

signal one tick 




LXI 

H, RTCCNT 

get div-by-60 cnt 




DCR 

M 

decrement counter 




JRNZ 

. .X 

not 60 ticks yet 




MV I 

M, 60 

reset counter 




CALL 

RTCSEC# 

signal one second 



. .X: 

POP 

H 

restore registers 




POP 

D 

n n 




POP 

B 

it if 




POP 

PSW 

if n 




LSPD 

INTSP# 

restore user’s SP 




JMP 

ISRXIT# 

go to dispatcher 
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If the hardware is capable of determining the 
date and time-of-day at cold-start (by means 
of a battery-powered clock, for example) , the 
clock driver may initialize the following 
public symbols in the RTCMGR module: 


SECS: : .BYTE 0 

MINS:: .BYTE 0 

HOURS:: .BYTE 0 
JDATE : : .WORD 8001H 


;seconds 0-59 
;minutes 0-59 
;hours 0-24 
;Julian date 
;base 31-Dec-47 
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The bootstrap is usually contained in a ROM 
or on a boot track. Its function is to 
search all disk drives for the TurboDOS 
loader program OSLOAD.COM, and to load and 
execute it if found. To generate a boot- 
strap, use the GEN command to combine the 
standard bootstrap module 0SB00T with your 
own hardwar e-dependent driver. Your driver 
must define the following public entry sym- 
bols: INIT, SELECT, READ, XFER, and RAM. 

INIT:: is called once to perform any required 
hardware initialization. It returns with the 
load base address (where OSLOAD.COM will be 
loaded) in HL. This address should normally 
be 0100H, but may have to be higher for a 
bootstrap ROM in low-memory. 

SELECT:: is called to select the disk drive 
passed in A (0-15). If the selected drive is 
not ready or non-existent, it returns A=0. 
Otherwise, it returns A=-l and the address of 
an 11-byte disk specification table (DST) in 
HL. The DST format is described on page 5-7. 

READ:: is called to read one physical sector 
from the last-selected drive. The track is 
passed in BC, the sector in DE, and the DMA 
address in HL. It must return A=0 if suc- 
cessful, or A=-l if an unrecoverable error 
occurred. 

XFER:: is transferred to at the end of the 
bootstrap process. In most cases, it needs 
only to set location 0080H to zero (to 
simulate a null command tail) and jump to 
0100H. However, if INIT returned a loader 
base other than 0100H, then XFER must move 
the loader down to 0100H before executing it. 

RAM:: defines a 64-byte area that 0SB00T can 
use for working storage. It should not be 
located where OSLOAD.COM will be loaded! 
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User OS 
Patch Points 


The following User 
supported. 

Patch 

Point 


OS Patch Points are 


Desc rip t ion, 


CONBR Baud rate patch point in module 

CON96 . Default = 9600-0CE. 

Baud Rate Code: 

bit 7 = 1 if attention detection 
is enabled 

bit 6 = 1 if clear-to-send hand- 
shaking enabled 

bit 5 = 1 if output-only (input 
disabled) 

bits 3-0 = baud-rate value 0..15 
(see table below) 

Notes: The least significant nibble of the 

E-register contains a baud rate value as 
follows : 


0 

= 50 

8 

= 

1,800 

1 

= 75 

9 

= 

2,000 

2 

= 110 

10 

= 

2,400 

3 

= 134.5 

11 

SS 

3,600 

4 

= 150 

12 

= 

4,800 

5 

= 300 

13 

S= 

7,200 

6 

= 600 

14 

= 

9,600 

7 

= 1,200 

15 

s 

19,200 


CTSBR Baud rate patch point, in LSTCTS 

module (see list above) . Default 
= 9600 = 04E. 

ETXBR Baud rate patch point, in LSTETX 

module (see list above) . Default 
= 1200 = 047. 


ETXLEN Block length prior to ETX signal, 

Default = 6E. 
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Patch 

Points Description 


XONBR Baud rate patch point in LSTXON 

module (see list above) . 


The following Server OS Patch Points are 
supported. 

Patch 

Points Description 


NSMTOP 

NSFTOP 


NMBHD5 


NMBHD18 


Top of physical memory, in 
MPEHRM module. Default = OFFFF . 

Top of memory above floppy con- 
troller, in MPEHRM module. 
Default * 0F000. 

HD5/15/30 disk partition flag. 

0 = one logical drive 
non-zero = two logical drives 
Default: 1 (two drives) 

HD1 8 disk partition flag. 
Settings same as NMBHD5 . 


Note: MPEHRM releases RAM from NSFTOP to 

NSMTOP to the TurboDOS memory pool. 

The following are all in the MCDUP8 module: 

CKTUP8 HRZ-UP8 board circuit number. 

Default = 0. 

NMBUP8 Number of HRZ-UP8*s supported. 

Default = 8. 


SSTUP8 


Suffix table for User OS 
Default = "AAAAAAAA" 
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PATUP8 I/O port addresses for 

HRZ-UP8s* Defaults = 

20 , 22 , 24, 26, 28, 2A, 2C, 2E. 
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